This tutorial will show you how to use the USAJOBS Historic JOAs API to obtain job postings filtered by a standard set of parameters. The base URL for the Search API is: https://data.usajobs.gov/api/historicjoa.
To instantiate the Historic JOAs REST API, first set up the request. Note that all interactions with USAJOBS are via HTTP. The request does not require parameters. The base URL for the Search API is: https://data.usajobs.gov/api/historicjoa.
var request = require('request'); request({ url: 'https://data.usajobs.gov/api/historicjoa', method: 'GET' }, function(error, response, body) { var data = JSON.parse(body); });
$ curl https://data.usajobs.gov/api/historicjoa
Next define optional query parameters that will be appended to the base URL to return a subset of JOAs. The full list of acceptable query parameters for this API endpoint can be found at: GET /api/HistoricJoa. For purposes of this tutorial, we will perform a search for Information Technology Management jobs which are defined by PositionSeries "2210".
var request = require('request'); request({ url: 'https://data.usajobs.gov/api/historicjoa?PositionSeries=2210', method: 'GET' }, function(error, response, body) { var data = JSON.parse(body); });
$ curl https://data.usajobs.gov/api/historicjoa?PositionSeries=2210
Once the request with parameters is made (Search Criteria: Jobs that have an position series "2210", Information Technology Management). Now, let's execute the code and view the results.
Search Result (JSON): { "paging": { "metadata": { "totalCount": 992, "pageSize": 10, "currentPage": 2, "totalPages": 100 }, "previous": "/api/historicjoa?PositionSeries=2210&pagesize=10&pagenumber=1", "next": "/api/historicjoa?PositionSeries=2210&pagesize=10&pagenumber=3" }, "data": [ { "usajobsControlNumber": 23728600, "hiringAgencyCode": "NF00 ", "hiringAgencyName": "National Science Foundation", "hiringDepartmentCode": "NF00 ", "hiringDepartmentName": "National Science Foundation", "agencyLevel": 1, "agencyLevelSort": "National Science Foundation", "appointmentType": "Permanent", "workSchedule": "Full-time", "payPlan": "GS", "salaryType": "Per Year", "vendor": "NA", "travelRequirement": "NA", "teleworkEligible": "N", "serviceType": "NA", "securityClearanceRequired": "N", "securityClearance": "NA", "whoMayApply": "Public", "announcementClosingTypeCode": "0", "announcementClosingTypeDescription": "NA", "positionOpenDate": "2016-12-01T00:00:00", "positionCloseDate": "2016-12-19T00:00:00", "positionExpireDate": "1900-01-01T00:00:00", "announcementNumber": "DIS-2017-0005", "hiringSubelementName": "NA", "positionTitle": "IT Specialist (IT Security & Privacy Policy & Planning), GS-2210-14 DE", "minimumGrade": "14", "maximumGrade": "14", "promotionPotential": "14", "minimumSalary": 108887.0000, "maximumSalary": 141555.0000, "supervisoryStatus": "Y", "drugTestRequired": "N", "relocationExpensesReimbursed": "Y", "totalOpenings": "0 ", "disableAppyOnline": "N", "positionOpeningStatus": "Applications under review", "hiringPaths": [], "jobCategories": [ { "series": "2210" } ], "positionLocations": [ { "positionLocationId": 963897, "positionLocationCity": "Arlington", "positionLocationState": "Virginia", "positionLocationCountry": "United States" } ] } ] }
{ "paging": { "metadata": { "totalCount": 992, "pageSize": 10, "currentPage": 2, "totalPages": 100 }, "previous": "/api/historicjoa?PositionSeries=2210&pagesize=10&pagenumber=1", "next": "/api/historicjoa?PositionSeries=2210&pagesize=10&pagenumber=3" }, "data": [ { "usajobsControlNumber": 23728600, "hiringAgencyCode": "NF00 ", "hiringAgencyName": "National Science Foundation", "hiringDepartmentCode": "NF00 ", "hiringDepartmentName": "National Science Foundation", "agencyLevel": 1, "agencyLevelSort": "National Science Foundation", "appointmentType": "Permanent", "workSchedule": "Full-time", "payPlan": "GS", "salaryType": "Per Year", "vendor": "NA", "travelRequirement": "NA", "teleworkEligible": "N", "serviceType": "NA", "securityClearanceRequired": "N", "securityClearance": "NA", "whoMayApply": "Public", "announcementClosingTypeCode": "0", "announcementClosingTypeDescription": "NA", "positionOpenDate": "2016-12-01T00:00:00", "positionCloseDate": "2016-12-19T00:00:00", "positionExpireDate": "1900-01-01T00:00:00", "announcementNumber": "DIS-2017-0005", "hiringSubelementName": "NA", "positionTitle": "IT Specialist (IT Security & Privacy Policy & Planning), GS-2210-14 DE", "minimumGrade": "14", "maximumGrade": "14", "promotionPotential": "14", "minimumSalary": 108887.0000, "maximumSalary": 141555.0000, "supervisoryStatus": "Y", "drugTestRequired": "N", "relocationExpensesReimbursed": "Y", "totalOpenings": "0 ", "disableAppyOnline": "N", "positionOpeningStatus": "Applications under review", "hiringPaths": [], "jobCategories": [ { "series": "2210" } ], "positionLocations": [ { "positionLocationId": 963897, "positionLocationCity": "Arlington", "positionLocationState": "Virginia", "positionLocationCountry": "United States" } ] } ] }
The search REST API returns a JSON object with the following attributes. A more detailed explanation of the response object can be found at: API-Reference/GET-api-HistoricJoa.
Combine any query parameters to further refine your search. All parameters support multiple search values which must be separated by a comma.
Lets take our current search for Information Technology Management positions and filter the results by using the StartPositionOpenDate and EndPositionOpenDate parameters. These options let you filter the Announcement Open date by a date range.
StartPositionOpenDate: 10-01-2015 EndPositionOpenDate: 09-30-2016
var request = require('request'); request({ url: 'https://data.usajobs.gov/api/historicjoa?PageSize=10&PageNumber=2&PositionSeries=2210&StartPositionOpenDate=10-01-2015&EndPositionOpenDate=09-30-2016', method: 'GET' }, function(error, response, body) { var data = JSON.parse(body); });
$ curl https://data.usajobs.gov/api/historicjoa?PositionSeries=2210&StartPositionOpenDate=10-01-2015&EndPositionOpenDate=09-30-2016
As a USAJOBS API Consumer, you agree to the following terms and conditions, and any policies, guidelines or amendments thereto that may be presented to you from time to time (collectively, the "Terms of Service") governing use of the USAJOBS API service. The Office of Personnel Management USAJOBS Program Office (OPM USAJOBS) may update the Terms of Service, and will notify you by email to accept the most current version of the Terms of Service. Inquiries should be sent via email: access@usajobs.gov
The API is described on the USAJOBS Developer site available here: https://developer.usajobs.gov. in consideration of your use of the api, you may be required to provide current, accurate identification, contact, and other information as part of the registration process and />or continued use of the services offered by OPM USAJOBS and its representatives. You are responsible for maintaining the confidentiality of your USAJOBS API key, and are responsible for all activities that occur under your account. You agree to immediately notify USAJOBS of any unauthorized use of your API key or any other breach of security. USAJOBS cannot and will not be liable for any loss or damage arising from your failure to comply with this.
USAJOBS reserves the right to refuse service to anyone at any time found to be in violation of this and subsequent sections. USAJOBS reserves the right at any time and from time to time to modify or discontinue, temporarily or permanently, the API (or any part thereof) with or without notice. You agree that USAJOBS shall not be liable to you or to any third party for any modification, suspension or discontinuance of USAJOBS services.
Data provided to you through the API is for the explicit use of the requesting company identified on the USAJOBS Program Office API Registration Form. No other use of the data provided is permitted without prior approval, in writing, from OPM USAJOBS. You may not rent, lease, loan, sell, trade or create derivative works of USAJOBS API services and data, in whole or in part.
The data provided through the API is restricted to publicly available information found in a USAJOBS JOA, contains no Personally-Identifiable Information (PII) of USAJOBS system users other than publicly disclosed contact information within the JOA, and may not exceed the Controlled Unclassified Information (CUI) designation.
You agree that you are responsible for your own conduct and the proper handling of any information made available while using the API and for any consequences thereof. You agree to use the API only for purposes that are legal, proper and in accordance with these Terms of Service and any applicable policies or guidelines. By way of example, and not as a limitation, you agree that when using the USAJOBS API, you will not:
You understand and agree that USAJOBS shall have the right (but not the obligation) in its sole discretion to deny access to those users that are found to be in violation of these Terms of Service.
By using the USAJOBS API service, you acknowledge and agree that OPM USAJOBS may access, preserve, and disclose your API account information or information about account activity if required to do so by law or in a good faith belief that such access preservation or disclosure is reasonably necessary to: (a) satisfy any applicable law, regulation, legal process or governmental request, (b) enforce this Terms of Service, including investigation of potential violations hereof, (c) detect, prevent, or otherwise address fraud, security or technical issues, (d) respond to JOA Consumer support requests, or (e) protect the rights, property or safety of USAJOBS, its users and the public. USAJOBS will not be responsible or liable for the exercise or non- exercise of its rights under the Terms of Service.
You understand that the technical processing and transmission of USAJOBS services, including API information, may involve (a) transmissions over various networks; and (b) changes to conform and adapt to technical requirements of connecting networks or devices.
You agree that OPM USAJOBS has no responsibility or liability for the deletion or failure to store any API service data. You acknowledge that OPM USAJOBS retains the right, at its sole discretion, to create limits at any time with or without notice on the number of API transactions the API Consumer may initiate, the size of API data files received, or the amount of storage space used.
You may cancel your use of the API with or without cause at any time by providing notice to USAJOBS at access@usajobs.gov; provided, however, that a terminated account may continue to exist until processed for removal and deletion under standard account management procedures. USAJOBS may at any time and for any reason, including a period of account inactivity, terminate your access. In the event of termination, your API key will be disabled and you may not be granted access to your API information.
API data may include links to World Wide Web sites or resources external to the USAJOBS information system. You acknowledge and agree that OPM is not responsible for the availability of such external sites or resources, and does not endorse and is not responsible or liable for any content available from such sites or resources, or your use or reliance on or through these resources.
You agree to hold harmless and indemnify USAJOBS, and its subsidiaries, affiliates, officers, agents, and employees, from and against any third party claim arising from or in any way related to your use of the API or violation of these Terms of Service including any liability or expense arising from all claims, losses, damages (actual and consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature. In such a case, USAJOBS will provide you with written notice of such claim, suit or action.
You expressly understand and agree that USAJOBS shall not be liable to you for any direct, indirect, incidental, special, consequential or exemplary damages resulting from: (i) the use or the inability to use the API; (ii) the cost of procurement of substitute goods and services resulting from any goods, data, information or services purchased or obtained or messages received or transactions entered into through or from the API; (iii) unauthorized access to or alteration of your transmissions or data; (iv) statements or conduct of any third party utilizing the API; or (v) any other matter relating to OPM USAJOBS.
Any material downloaded or otherwise obtained through the use of the API is done at your own discretion and risk and that you will be solely responsible for any damage to your computer system or loss of data that results from the download of any such material.
No advice or information, whether oral or written, obtained by you from OPM shall create any warranty.
You agree that there shall be no third party beneficiaries to the Terms of Service.
The Terms of Service constitute the entire agreement between you and OPM governing your use of the USAJOBS API service as an API Consumer. You also may be subject to additional terms and conditions that may apply when you use other USAJOBS services.
The failure of USAJOBS to exercise or enforce any right or provision of the Terms of Service shall not constitute a waiver of such right or provision.
An official website of the United States Government
An official website of the United States Government