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