Get Opportunities Public API documentation

Size: px

Start display at page:

Download "Get Opportunities Public API documentation"

Irma Baker
5 years ago
Views:

1 documentation Prepared for General Services Administration (GSA) Integrated Award Environment (IAE)

Table of Contents 1. Overview... 2 2. Get Opportunities Request Parameters... 2 3. Get Opportunities Response Parameters... 5 4. Examples... 7 4.1 Example 1: Search opportunities for the given date.

2 Table of Contents 1. Overview Get Opportunities Request Parameters Get Opportunities Response Parameters Examples Example 1: Search opportunities for the given date Example 2: Search by pre-solicitation type Example 3: Search for opportunities by a given title API Versions Authentication and API Keys Synchronous vs Asynchronous call HTTP Response Codes Error Messages

3 1. Overview Get Opportunities API provides all the published opportunity details based on the request parameters. This API supports pagination as needed. If pagination is requested, then the response will be provided to users synchronously else the call will be asynchronous. 2. Get Opportunities Request Parameters Users can search by any of the below request parameters with Date field as mandatory. Table 1: Opportunities GET API Request Parameters Request Parameters that API accepts Description Mandatory? Data Type api_key Public Key of users Yes ptype Procurement Type. Below are the available Procurement Types: u= Justification (J&A) p = Pre solicitation a = Award Notice r = Sources Sought s = Special Notice g = Sale of Surplus Property k = Combined Synopsis/Solicitation i = Intent to Bundle Requirements (DoD- Funded) No Note: Below services are now retired: f = Foreign Government Standard l = Fair Opportunity / Limited Sources Use Justification (u) instead of fair Opportunity. solnum Solicitation Number No title Title No description Description No postedfrom Posted date From. Yes Format must be MM/dd/yyyy Note: Date range between Posted Date From and To is 1 year postedto Posted date To Yes Format must be MM/dd/yyyy Note: Date range between Posted Date From and To is 1 year 2

4 status Status of record. Must be one of No Active/Inactive/Both Default status: Active deptname Department Name (L1) No subtier Agency Name (L2) No state Place of Performance (State) No zip Place of Performance (Zip code) No typeofsetaside Legacy Set Aside codes & their descriptions are: No 1 = Partial Small Business 2 = Partial HBCU / MI 3 = Service-Disabled Veteran-Owned Small Business 4 = Total Women-owned Business 5 = HUBZone 6 = Total Small Disadvantage Business 7 = Total Small Business 8 = Veteran-Owned Small Business 9 = Total HBCU / MI 10 = Partial Women-owned Business 11 = Partial HUB-Zone 12 = Partial Small Disadvantage Business 13 = Very Small Business 14 = Competitive 8(a) 15 = Emerging Small Business 16 = Woman Owned Small Business 17 = Economically Disadvantaged Woman Owned Small Business 18 = Indian Economic Enterprises 19 = Indian Small Business Economic Enterprises Modern Set Aside codes & their descriptions are: = Total Small Business Set- Aside (FAR 19.5) = Partial Small Business Set- Aside (FAR 19.5) = 8(a) Set-Aside (FAR 19.8) = 8(a) Sole Source (FAR 19.8) = Historically Underutilized Business (HUBZone) Set-Aside (FAR 19.13) 3

5 = Historically Underutilized Business (HUBZone) Sole Source (FAR 19.13) = Service-Disabled Veteran- Owned Small Business (SDVOSB) Set- Aside (FAR 19.14) = Service-Disabled Veteran- Owned Small Business (SDVOSB) Sole Source (FAR 19.14) = Women-Owned Small Business (WOSB) Program Set-Aside (FAR 19.15) = Women-Owned Small Business (WOSB) Program Sole Source (FAR 19.15) = Economically Disadvantaged WOSB (EDWOSB) Program Set-Aside (FAR 19.15) = Economically Disadvantaged WOSB (EDWOSB) Program Sole Source (FAR 19.15) = Local Area Set-Aside (FAR 26.2) = Indian Economic Enterprise (IEE) Set-Aside (specific to Department of Interior) = Indian Small Business Economic Enterprise (ISBEE) Set-Aside (specific to Department of Interior) = Buy Indian Set-Aside (specific to Department of Health and Human Services, Indian Health Services) = Veteran-Owned Small Business Set-Aside (specific to Department of Veterans Affairs) = Veteran-Owned Small Business Sole source (specific to Department of Veterans Affairs) Note: Backend is making a transition to the modern set aside codes in phases. Hence the document lists both the setaside codes for now. typeofsetasidedescription Set Aside code Description. See above descriptions mentioned against each of No 4

6 the Set Aside Code ncode NAICS Code. This code is maximum of 6 No digits ccode Classification Code No rdlfrom Response Deadline date. Format must be No MM/dd/yyyy Note: If response date From & To is provided, then the date range is 1 year rdlto Response Deadline date. Format must be No MM/dd/yyyy Note: If response date From & To is provided, then the date range is 1 year limit Total number of records to be retrieved No Int per page. This field must be a number. NOTE: If limit is not provided, request will be treated as an asynchronous request and users will receive an with a download option to retrieve response. offset Indicates the page index. Default offset starts with 0 No Int 3. Get Opportunities Response Parameters Based on the request parameters, API provides below response parameters. Table 2: GET Opportunities API Response Parameters Response Parameters that API provides Description Data Type totalrecords Total number of records for the search Number limit Limit entered by a user while making the request i.e. total number of records that user wished to retrieve per page. Number offset Page index specified by a user. Default offset starts with 0 if user does not provide any offset in the request. Number title Opportunity Title solicitationnumber Solicitation Number department Department (L1) subtier Sub-Tier (L2) office Office (L3) posteddate Opportunity Posted Date YYYY-MM-DD HH:MM:SS 5

7 type Opportunity current type basetype Opportunity original type archivetype Archive Type archivedate Archived Date setaside Set Aside Description setasidecode Set Aside Code reponsedeadline Response Deadline Date naicscode NAICS Code. This code is maximum of 6 digits. classificationcode Classification Code active If Active = Yes, then the opportunity is active, if No, then opportunity is Archived. award Award Information (If Available) This will have JSON - Award amount - Awardee - Award date - Award Number pointofcontact Point of Contact Information. It can have below fields if available JSON - Fax - Type - - Phone - Title - Full name description A link to an opportunity description. Note: To download the description, user should append the public API Key. If no description is available then, user is shown an error message Description not found organizationtype Type of an organization department/subtier/office officeaddress Office Mailing Address placeofperformance Place of performance information. It can have JSON below fields if available - Street Address - City (City code & Name) - State (State Code Only) - Country (Country Code Only) - Zip additionalinfolink Any additional info link if available for the opportunity uilink Direct UI link to the opportunity. To view the opportunity on UI, user must have either a 6

8 links contracting officer or a Contracting Specialist role. If user hits the link without logging in, user is directed to 404 not found page. Every record in a response has this links array consisting of: - rel: self - href: link to the specific opportunity itself. User should provide an API key to access the opportunity directly Also, every response has a master links array consisting of - rel: self - href: link to the actual request. User should provide an API key to access the request Array 4. Examples URLs for production and staging: Production URL: Staging URL: Example 1: Search opportunities for the given date Request URL s Public API Key&postedFrom=01/01/2018&postedTo=05/10/2018 Note: Request URL for staging is used in this example Response (JSON Output) Note: Response for one record is provided as an example "totalrecords": 25543, "limit": 10, "offset": 1, "opportunitiesdata": [ "noticeid": "ea55e45cded123fd8d6afd7c061138f0", "title": "Judge Rice Courtroom Lighting Project", "solicitationnumber": "EQ5P2SS2P ", 7

9 "department": null, "subtier": null, "office": null, "posteddate": " :45:22+00", "type": "Presolicitation", "basetype": "Presolicitation", "archivetype": "manual", "archivedate": null, "typeofsetasidedescription": null, "typeofsetaside": "7", "responsedeadline": null, "naicscode": "236220", "classificationcode": "Z", "active": "Yes", "award": null, "pointofcontact": [ "fax": null, "type": "primary", " ": "jordan.waldschmidt@gsa.gov", "phone": " ", "title": "Contract Specialist", "fullname": "Jordan Waldschmidt" "fax": null, "type": "secondary", " ": "johanna.nieves@gsa.gov", "phone": " ", "title": "Contracting Officer", "fullname": "Johanna Nieves" ], "description": " /opportunities/v1/noticedesc?noticeid=ea55e45cded123fd8d6afd7c061138f0", "organizationtype": null, "officeaddress": null, "placeofperformance": "streetaddress": "Dayton Federal Building and US Courthouse\r\n200 West Second Street", "city": "code": "21000", "name": "21000" "state": 8

10 "code": "OH" "zip": "45402", "country": "code": "USA" "additionalinfolink": null, "uilink": " "links": [ "rel": "self", "href": " &limit=" ] 4.2 Example 2: Search by pre-solicitation type Request URL s Public API Key &postedfrom=01/01/2018&postedto=05/10/2018&ptype=p Note: Request URL for staging is used in this example Response (JSON Output) Note: Response for one record is provided as an example "totalrecords": 11035, "limit": 10, "offset": 0, "opportunitiesdata": [ "noticeid": "ea55e45cded123fd8d6afd7c061138f0", "title": "Judge Rice Courtroom Lighting Project", "solicitationnumber": "EQ5P2SS2P ", "department": null, "subtier": null, "office": null, "posteddate": " :45:22+00", "type": "Presolicitation", 9

11 "basetype": "Presolicitation", "archivetype": "manual", "archivedate": null, "typeofsetasidedescription": null, "typeofsetaside": "7", "responsedeadline": null, "naicscode": "236220", "classificationcode": "Z", "active": "Yes", "award": null, "pointofcontact": [ "fax": null, "type": "primary", " ": "jordan.waldschmidt@gsa.gov", "phone": " ", "title": "Contract Specialist", "fullname": "Jordan Waldschmidt" "fax": null, "type": "secondary", " ": "johanna.nieves@gsa.gov", "phone": " ", "title": "Contracting Officer", "fullname": "Johanna Nieves" ], "description": " 8f0", "organizationtype": null, "officeaddress": null, "placeofperformance": "streetaddress": "Dayton Federal Building and US Courthouse\r\n200 West Second Street", "city": "code": "21000", "name": "21000" "state": "code": "OH" "zip": "45402", "country": 10

12 "code": "USA" "additionalinfolink": null, "uilink": " "links": [ "rel": "self", "href": " &limit=" ] 4.3 Example 3: Search for opportunities by a given title Request URL /opportunities/v1/search?limit=10&api_key=user s Public API Key&postedFrom=01/01/2018&postedTo=05/10/2018&title=Driving Note: Request URL for staging is used in this example Response (JSON Output) Note: Response for one record is provided as an example "totalrecords": 12, "limit": 10, "offset": 0, "opportunitiesdata": [ "noticeid": "9ffb613fb bbbf250cd8292d", "title": "DIFFERENTIAL, DRIVING", "solicitationnumber": "SPRDL118R0216", "department": null, "subtier": null, "office": null, "posteddate": " :41:13+00", "type": "Presolicitation", "basetype": "Presolicitation", "archivetype": "manual", "archivedate": null, "typeofsetasidedescription": null, 11

13 "typeofsetaside": null, "responsedeadline": " T20:00:00-05:00", "naicscode": "336350", "classificationcode": "25", "active": "Yes", "award": null, "pointofcontact": [ "fax": null, "type": "primary", " ": "vincent.strongarone@dla.mil", "phone": null, "title": null, "fullname": "vincent strongarone" "fax": null, "type": "secondary", " ": "DLALandWarrenFBO@dla.mil", "phone": null, "title": null, "fullname": "DLA FBO Mailbox" ], "description": " 92d", "organizationtype": null, "officeaddress": null, "placeofperformance": null, "additionalinfolink": null, "uilink": " "links": [ "rel": "self", "href": " &limit=" ] 12

14 5. API Versions Version Authentication and API Keys Users of this public API must provide an API key to use this Opportunities public API. Request per day are limited based on the federal or non-federal or general roles. Note: Users can request a public API Key in their Account Details page on beta.sam.gov (if testing in production) Else on alpha.sam.gov (if testing in prodlike). 7. Synchronous vs Asynchronous call Since Opportunities data volume is huge, API works as follows: If limit is provided (limit range is ), then the API will give response immediately (synchronous call). If limit is not provided, then the API will work asynchronously and sends an to the user with the response as a downloadable link. This downloadable link will have an expiry time. The downloadable CSV file format is: "Title", "Sol#", "Department/Ind.Agency", "Sub-Tier", "Office", "PostedDate", "Type", "BaseType", "ArchiveType", "ArchiveDate", "SetASideCode", "SetASide", "ResponseDeadLine", "NaicsCode", "ClassificationCode", "PopStreetAddress", "PopCity", "PopState", "PopZip", "PopCountry", "Active", "AwardNumber", "AwardDate", "Award$", "Awardee", "PrimaryContactTitle", "PrimaryContactFullname", "PrimaryContact ", "PrimaryContactPhone", "PrimaryContactFax", "SecondaryContactTitle", "SecondaryContactFullname","SecondaryContact ", "SecondaryContactPhone", "SecondaryContactFax","Description","OrganizationType","StreetAddress","StreetA ddress2","state","city","zipcode","countrycode","additionalinfolik", "Link" 8. HTTP Response Codes Success 404 No Data found 13

15 400 Bad Request 500 Internal Server Error 9. Error Messages # Scenario Error Messages 1 For status, user provides a value apart from Both or Active or InActive. Invalid Status value. Allowed values are any of Both/Active/InActive 2 For limit, user provides range beyond Limit valid range is Please provide valid input. 3 For limit or offset, user inputs characters/special characters. limit/offset must be a positive number. 4 For postedfrom, postedto, rdlfrom, rdlto user enters an invalid date format. 5 User does not provide postedfrom and postedto values. 6 User provides more than 1 year of date range for postedfrom and postedto. OR User provides more than 1 year of date range for rdlfrom and rdlto 7 User provides more than 25 characters for description field. Invalid Date Entered. Expected date format is MM/dd/yyyy PostedFrom and PostedTo are mandatory Date range must be 1 year(s) apart Description length is limited to 25 characters 8 User provides invalid API Key An invalid api_key was supplied. Get one at Note: This URL does not work at this point. Please refer section 6 on how to get API keys 9 User does not provide any API key No api_key was supplied. Get one at Note: This URL does not work at this point. Please 14

16 refer section 6 on how to get API keys 10 User clicks on the description link available in the response and description content is not available Description Not Found 15

HUBZone Program First Wednesday Virtual Learning Series 2018

HUBZone Program First Wednesday Virtual Learning Series 2018 www.sba.gov 1 Hosts Christopher Eischen, Procurement Center Representative SBA Office of Government Contracting, Area IV, Kansas City, MO christopher.eischen@sba.gov