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.

JavaScript
cURL
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".

JavaScript
cURL
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
JavaScript
cURL
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