Tutorials - Search Jobs

This tutorial will show you how to search USAJOBS for open job opportunity announcments using the REST based API. A detailed reference on this API endpoint can be found at GET /api/Search.

Before proceeding with this tutorial you will first need to obtain an API Key if you do not already have one. To request an API Key, please go the the API Request page and fill out an application.

Step 1: Set up a request

To instantiate the Search REST API, we first need to set up the request. Note that all interactions with USAJOBS are via HTTP. The request must include 3 parameters defined in the header, which include: Host, User Agent, and Authorization Key. The base URL for the Search API is: https://data.usajobs.gov/api/search.

JavaScript
cURL
var request = require('request');  
              
var host = 'data.usajobs.gov';  
var userAgent = 'your@email.address';  
var authKey = 'YourAPIKey';    
            
request({      
    url: 'https://data.usajobs.gov/api/search',      
    method: 'GET',      
    headers: {          
        "Host": host,          
        "User-Agent": userAgent,          
        "Authorization-Key": authKey      
    }  
}, function(error, response, body) {      
    var data = JSON.parse(body);  
});

$ curl -H "Host: data.usajobs.gov"    
  -H "User-Agent: $YOUR_EMAIL"    
  -H "Authorization-Key: $AUTH_KEY"    
  https://data.usajobs.gov/api/search

Step 2: Define query paramters

Now we have the structure of our request built, we need to define query parameters that will be appended to the base URL to drive the specific results desired. The full list of acceptable query parameters for this API endpoint can be found at: GET /api/Search. For purposes of this tutorial, we will perform a search for Information Technology Management jobs which are defined by Occupational Series "2210". A complete list of Agency Subelement codes can be found at: API-Reference/GET-codelist-agencysubelements.

JavaScript
cURL
var request = require('request');    
            
var host = 'data.usajobs.gov';  
var userAgent = 'your@email.address';  
var authKey = 'YourAPIKey';    
            
request({      
    url: 'https://data.usajobs.gov/api/search?JobCategoryCode=2210&Keyword=Software Development&LocationName=Washington, DC',      
    method: 'GET',      
    headers: {          
        "Host": host,          
        "User-Agent": userAgent,          
        "Authorization-Key": authKey      
    }  
}, function(error, response, body) {      
    var data = JSON.parse(body);  
});
$ curl -H "Host: data.usajobs.gov"    
-H "User-Agent: $YOUR_EMAIL"    
-H "Authorization-Key: $AUTH_KEY"    
https://data.usajobs.gov/api/search?JobCategoryCode=2210

Step 3: Execute Job Search

We have set up the logic to make a request and defined what we are searching for (Search Criteria: Jobs that have an occupational series "2210", Information Technology Management). Now, let's execute the code and view the results. 

Search Result (JSON):
{     
    "LanguageCode": "EN",     
    "SearchParameters": { },     
    "SearchResult": {         
        "SearchResultCount": 25,         
        "SearchResultCountAll": 279,         
        "SearchResultItems": [...],         
        "UserArea": {             
            "NumberOfPages": "12",             
            "IsRadialSearch": false         
        }     
    } 
}

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-Search.

Name Description Type
LanguageCode Response Langauge String
SearchParameters Query parameters used in search request. Object
SearchResult Object
 SearchResultCount Number of records returned in response object. Integer
 SearchResultCountAll Total Number of records that matched search criteria. Integer
 SearchResultItems Array of job opportunity announcement objects that matched search criteria. Array
 UserAreas Object
  NumberOfPages Number of pages based on SearchResultCount divided by SearchResultCountAll. Integer
  IsRadialSearch If a radial search was used or not. Boolean

After looking at the response, we see that our search matched 279 jobs and returned the first 25 matches. Let's be more specific in our search to improve our results and reduce the number of matches. The next step will show you how you can use multiple query parameters in your search.

Note: The number of results returned per request defaults to 25 but can be defined in your request up to 500 per request.

Step 4: Combine query parameters to refine search

You can use any combination of query parameters to further refine your search. All parameters support multiple search values which must be separated by a colon.

Lets take our current search for Information Technology Management positions and filter the results by using the keyword and location query parameters.

 Keyword: Software Development LocationName: Washington, DC
JavaScript
cURL
var request = require('request');    
            
var host = 'data.usajobs.gov';  
var userAgent = 'your@email.address';  
var authKey = 'YourAPIKey';    
            
request({      
    url: 'https://data.usajobs.gov/api/search?JobCategoryCode=2210&Keyword=Software Development&LocationName=Washington, DC',      
    method: 'GET',      
    headers: {          
        "Host": host,          
        "User-Agent": userAgent,          
        "Authorization-Key": authKey      
    }  
}, function(error, response, body) {      
    var data = JSON.parse(body);  
});
$ curl -H "Host: data.usajobs.gov"    
  -H "User-Agent: $YOUR_EMAIL"    
  -H "Authorization-Key: $AUTH_KEY"    
  https://data.usajobs.gov/api/search?JobCategoryCode=2210&Keyword=Software Development&LocationName=Washington, DC