Tutorials - Past job announcements
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.
Step 1: Set up a request
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
Step 2: Define query parameters
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
Step 3: Execute Job Search
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"
}
]
}
]
}
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.
Step 4: Combine query parameters to refine search
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