Banner: Web API: List jobs

Web API: List jobs

List jobs

'List Jobs' is an API that enables developers to retrieve job postings for a specific keyword or an occupation title or code. The returned list object contains the job postings available in the area, from the National Labor Exchange. The API provides search results based on keyword and location entered. The search recognizes the O*NET taxonomy created by the Department of Labor for cross-agency use by federal, state and local government entities.

About this data

The API is used in the CareerOneStop Job Finder tool. More information about the data is available on the Job Finder Help page. Check out the NASWA research hub for information on using Jobs data from NLx (National Labor Exchange) for analytical or research purposes. Check out information about upcoming updates.

Resource URL

https://api.careeronestop.org/v1/jobsearch/{userId}/{keyword}/{location}/{radius}/{sortColumns}/{sortOrder}/{startRecord}/{pageSize}/{days}

Try this Web API

Example Code

using System;

using System.Net.Http;

using System.Net.Http.Headers;

using System.Threading.Tasks;

using System.Collections.Specialized;

using System.Linq;

namespace CareerOneStopAPISample

{

    class Program

    {

        static void Main(string[] args)

        {

            CreateRequest().Wait();

        }

        private static async Task CreateRequest()

        {

            var qs = new NameValueCollection();

            qs["companyName"] = "value";                       

           

            var uri = new UriBuilder(Uri.UriSchemeHttps, "api.careeronestop.org")

            {

                Path = "/v1/jobsearch/{userId}/{keyword}/{location}/{radius}/{sortColumns}/{sortOrder}/{startRecord}/{pageSize}/{days}",

                Query = string.Join("&", qs.AllKeys.Select(key => key + "=" + Uri.EscapeUriString(qs[key])))

            };

           

            using (var http = new HttpClient())

            {

                http.DefaultRequestHeaders.Accept.Clear();

                http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "Your API Token");

                http.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

                var response = await http.GetAsync(uri.Uri).ConfigureAwait(false);

                if (response.IsSuccessStatusCode)

                {

                    var result = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                }

            }

        }

    }

}
import java.io.IOException;

import java.net.URI;

import java.net.URISyntaxException;

import org.apache.http.HttpEntity;

import org.apache.http.client.methods.CloseableHttpResponse;

import org.apache.http.client.methods.HttpGet;

import org.apache.http.client.utils.URIBuilder;

import org.apache.http.impl.client.CloseableHttpClient;

import org.apache.http.impl.client.HttpClients;

import org.apache.http.util.EntityUtils;

public class CareerOneStopAPISample {

    public static void main(String[] args) throws IOException, URISyntaxException {

    URI uri = new URIBuilder()

        .setScheme("https")

        .setHost("api.careeronestop.org")

        .setPath("/v1/jobsearch/{userId}/{keyword}/{location}/{radius}/{sortColumns}/{sortOrder}/{startRecord}/{pageSize}/{days}")

                .setParameter("companyName", "value")

        .build();

    CloseableHttpResponse response = null;

    HttpGet httpGet = null;

    try {

        CloseableHttpClient httpClient = HttpClients.createDefault();

        httpGet = new HttpGet(uri);

        httpGet.setHeader("Content-Type","application/json");

        httpGet.setHeader("Authorization", "Bearer Your API Token");

        response = httpClient.execute(httpGet);

        HttpEntity entity = response.getEntity();

        System.out.println(EntityUtils.toString(entity));

    } finally {

        if(httpGet != null) httpGet.releaseConnection();

        if(response != null) response.close();

    }

   }

}

Request Parameters

Refer to the following table for a list of the required and optional request parameters. All parameter names and values are case sensitive. Important: You must provide all required parameters. Submitting an empty request does not return all possible results, an empty request returns an error.

Parameter Name Value Required? Description
API Token
String
Required
This value is the unique API Token provided during the CareerOneStop Web API registration process
userId
String
Required
This value is the unique UserID provided during the CareerOneStop Web API registration process
keyword
String
Required
Search term for the job search. To request all jobs within a city, a ZIP code, or a state, use keyword "0". An actual keyword is required for nationwide searches. When either keyword is an O*NET code or title, this API will search for jobs matching either that code OR the corresponding title.
location
String Required This value accepts a city, state (Chicago, IL) or state (IL) or ZIP code (61299). Use "US" for a nationwide search.
radius
String Required
The radius, in miles of the job opportunities search area. Applies to searches by city or ZIP code.
days Integer Required Number of days to go back to get the job postings. Use 0 to get all postings, regardless of age.
sortColumns
String Required

This value determines the sort order, that is, by which property (column) the postings are sorted. Valid values are:
0 (default) - sorts by relevance to the search term
jobtitle
company
location
accquisitiondate

sortOrder
String Required

Use this parameter in conjunction with sortColumns to set the order of the results. Valid values are:
0 (default) – use sortOrder=0 with sortColumns=0 to get the most relevant postings first
ASC – ascending; A-Z, or old to new
DESC – descending; Z-A, or new to old

startRow
Integer
Required
Specifies the start row. Allowed values are 0 (first record) to 500.
pageSize
Integer
Required
This value is the number of results to be returned by Web API.
companyName
String
Optional
Company by which you may want to filter job results. 
locationFilter
String
Optional
Location by which you may want to filter job results. If you provide a value in locationFilter, then that value pre-empts any value in “location” parameter, and we use a radius of “0” (pre-empting any value in the “radius” parameter).
showFilters
String
Optional
The flag value to include company and location filter values in the response.

Response Structure

{
  "Jobcount": "10407",
  "Jobs": [
    {
      "JvId": "48D0F7F8DDC34BE9ABE5F8498D815202206",
      "JobTitle": "Nurse",
      "Company": "Veterans Affairs, Veterans Health Administration",
      "AccquisitionDate": "2020-11-19 6:24 AM",
      "URL": "https://de.jobsyn.org/48D0F7F8DDC34BE9ABE5F8498D815202206",
      "Location": "Clarksburg, West Virginia",
      "Fc": "False"
    },
    {
      "JvId": "33F18D2F10914C9E803B5A06BC092B5B206",
      "JobTitle": "Nurse",
      "Company": "Jewish Community Center",
      "AccquisitionDate": "2020-9-16 8:55 PM",
      "URL": "https://de.jobsyn.org/33F18D2F10914C9E803B5A06BC092B5B206",
      "Location": "Richmond, Virginia",
      "Fc": "False"
    },
    {
      "JvId": "A1F26D62E9344ED6ACB49A7ED3505CD2206",
      "JobTitle": "Nursing Faculty",
      "Company": "Virginia State Government",
      "AccquisitionDate": "2020-11-25 9:01 PM",
      "URL": "https://de.jobsyn.org/A1F26D62E9344ED6ACB49A7ED3505CD2206",
      "Location": "Gloucester, Virginia",
      "Fc": "False"
    },
    {
      "JvId": "EB97E4084E5143298AA00171913D6379206",
      "JobTitle": "Registered Nurse",
      "Company": "Virginia State Government",
      "AccquisitionDate": "2020-11-16 9:00 PM",
      "URL": "https://de.jobsyn.org/EB97E4084E5143298AA00171913D6379206",
      "Location": "Staunton, Virginia",
      "Fc": "False"
    },
    {
      "JvId": "1F0F417166DF4C9E910C30A5923F04A5206",
      "JobTitle": "Registered Nurse",
      "Company": "Virginia State Government",
      "AccquisitionDate": "2020-11-16 9:00 PM",
      "URL": "https://de.jobsyn.org/1F0F417166DF4C9E910C30A5923F04A5206",
      "Location": "Danville, Virginia",
      "Fc": "False"
    },
    {
      "JvId": "32E57272FAA745E8B3F3C89757731C91206",
      "JobTitle": "Nurse Practitioner",
      "Company": "American Medical Facilities Management",
      "AccquisitionDate": "2020-11-20 7:22 AM",
      "URL": "https://de.jobsyn.org/32E57272FAA745E8B3F3C89757731C91206",
      "Location": "Bluefield, West Virginia",
      "Fc": "False"
    },
    {
      "JvId": "2CD787445A0742389099E1673B267CA6206",
      "JobTitle": "Clinic Nurse",
      "Company": "George Mason University",
      "AccquisitionDate": "2020-7-8 8:40 PM",
      "URL": "https://de.jobsyn.org/2CD787445A0742389099E1673B267CA6206",
      "Location": "Fairfax, Virginia",
      "Fc": "False"
    },
    {
      "JvId": "57FB0872F5F0421EB99A8F4C0CBA5B44206",
      "JobTitle": "Wound Nurse Registered Nurse",
      "Company": "Novant Health",
      "AccquisitionDate": "2020-9-18 10:50 PM",
      "URL": "https://de.jobsyn.org/57FB0872F5F0421EB99A8F4C0CBA5B44206",
      "Location": "Manassas, Virginia",
      "Fc": "False"
    },
    {
      "JvId": "295372884A464C02B59A2D34D7D05213206",
      "JobTitle": "Graduate Nurse",
      "Company": "Princeton Community Hospital",
      "AccquisitionDate": "2020-11-25 8:41 AM",
      "URL": "https://de.jobsyn.org/295372884A464C02B59A2D34D7D05213206",
      "Location": "Princeton, West Virginia",
      "Fc": "False"
    },
    {
      "JvId": "9F0C1A5B7AB1469CA7A472B2CF8AA8C4206",
      "JobTitle": "Registered Nurse",
      "Company": "West Virginia Employer",
      "AccquisitionDate": "2019-8-30 8:12 PM",
      "URL": "https://de.jobsyn.org/9F0C1A5B7AB1469CA7A472B2CF8AA8C4206",
      "Location": "Elkins, West Virginia",
      "Fc": "False"
    }
  ],
  "Locations": null,
  "Companies": null,
  "JobsKeywordLocations": {
    "Keyword": "nurse",
    "Location": "\"va\"",
    "IsValidLocation": true,
    "Radius": "0",
    "StartRow": "0",
    "EndRow": "10",
    "IsCode": false,
    "Title": null,
    "LocationState": "Virginia",
    "Message": null
  }
}

<ListJobSearch xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/XPAND.CareerOneStop.WebApi.ViewModels">
<Companies i:nil="true"/>
<Jobcount>10407</Jobcount>
<Jobs>
<Job>
<AccquisitionDate>2020-11-19 6:24 AM</AccquisitionDate>
<Company>Veterans Affairs, Veterans Health Administration</Company>
<Fc>False</Fc>
<JobTitle>Nurse</JobTitle>
<JvId>48D0F7F8DDC34BE9ABE5F8498D815202206</JvId>
<Location>Clarksburg, West Virginia</Location>
<URL>https://de.jobsyn.org/48D0F7F8DDC34BE9ABE5F8498D815202206</URL>
</Job>
<Job>
<AccquisitionDate>2020-9-16 8:55 PM</AccquisitionDate>
<Company>Jewish Community Center</Company>
<Fc>False</Fc>
<JobTitle>Nurse</JobTitle>
<JvId>33F18D2F10914C9E803B5A06BC092B5B206</JvId>
<Location>Richmond, Virginia</Location>
<URL>https://de.jobsyn.org/33F18D2F10914C9E803B5A06BC092B5B206</URL>
</Job>
<Job>
<AccquisitionDate>2020-11-25 9:01 PM</AccquisitionDate>
<Company>Virginia State Government</Company>
<Fc>False</Fc>
<JobTitle>Nursing Faculty</JobTitle>
<JvId>A1F26D62E9344ED6ACB49A7ED3505CD2206</JvId>
<Location>Gloucester, Virginia</Location>
<URL>https://de.jobsyn.org/A1F26D62E9344ED6ACB49A7ED3505CD2206</URL>
</Job>
<Job>
<AccquisitionDate>2020-11-16 9:00 PM</AccquisitionDate>
<Company>Virginia State Government</Company>
<Fc>False</Fc>
<JobTitle>Registered Nurse</JobTitle>
<JvId>EB97E4084E5143298AA00171913D6379206</JvId>
<Location>Staunton, Virginia</Location>
<URL>https://de.jobsyn.org/EB97E4084E5143298AA00171913D6379206</URL>
</Job>
<Job>
<AccquisitionDate>2020-11-16 9:00 PM</AccquisitionDate>
<Company>Virginia State Government</Company>
<Fc>False</Fc>
<JobTitle>Registered Nurse</JobTitle>
<JvId>1F0F417166DF4C9E910C30A5923F04A5206</JvId>
<Location>Danville, Virginia</Location>
<URL>https://de.jobsyn.org/1F0F417166DF4C9E910C30A5923F04A5206</URL>
</Job>
<Job>
<AccquisitionDate>2020-11-20 7:22 AM</AccquisitionDate>
<Company>American Medical Facilities Management</Company>
<Fc>False</Fc>
<JobTitle>Nurse Practitioner</JobTitle>
<JvId>32E57272FAA745E8B3F3C89757731C91206</JvId>
<Location>Bluefield, West Virginia</Location>
<URL>https://de.jobsyn.org/32E57272FAA745E8B3F3C89757731C91206</URL>
</Job>
<Job>
<AccquisitionDate>2020-7-8 8:40 PM</AccquisitionDate>
<Company>George Mason University</Company>
<Fc>False</Fc>
<JobTitle>Clinic Nurse</JobTitle>
<JvId>2CD787445A0742389099E1673B267CA6206</JvId>
<Location>Fairfax, Virginia</Location>
<URL>https://de.jobsyn.org/2CD787445A0742389099E1673B267CA6206</URL>
</Job>
<Job>
<AccquisitionDate>2020-9-18 10:50 PM</AccquisitionDate>
<Company>Novant Health</Company>
<Fc>False</Fc>
<JobTitle>Wound Nurse Registered Nurse</JobTitle>
<JvId>57FB0872F5F0421EB99A8F4C0CBA5B44206</JvId>
<Location>Manassas, Virginia</Location>
<URL>https://de.jobsyn.org/57FB0872F5F0421EB99A8F4C0CBA5B44206</URL>
</Job>
<Job>
<AccquisitionDate>2020-11-25 8:41 AM</AccquisitionDate>
<Company>Princeton Community Hospital</Company>
<Fc>False</Fc>
<JobTitle>Graduate Nurse</JobTitle>
<JvId>295372884A464C02B59A2D34D7D05213206</JvId>
<Location>Princeton, West Virginia</Location>
<URL>https://de.jobsyn.org/295372884A464C02B59A2D34D7D05213206</URL>
</Job>
<Job>
<AccquisitionDate>2019-8-30 8:12 PM</AccquisitionDate>
<Company>West Virginia Employer</Company>
<Fc>False</Fc>
<JobTitle>Registered Nurse</JobTitle>
<JvId>9F0C1A5B7AB1469CA7A472B2CF8AA8C4206</JvId>
<Location>Elkins, West Virginia</Location>
<URL>https://de.jobsyn.org/9F0C1A5B7AB1469CA7A472B2CF8AA8C4206</URL>
</Job>
</Jobs>
<JobsKeywordLocations>
<EndRow>10</EndRow>
<IsCode>false</IsCode>
<IsValidLocation>true</IsValidLocation>
<Keyword>nurse</Keyword>
<Location>"va"</Location>
<LocationState>Virginia</LocationState>
<Message i:nil="true"/>
<Radius>0</Radius>
<StartRow>0</StartRow>
<Title i:nil="true"/>
</JobsKeywordLocations>
<Locations i:nil="true"/>
</ListJobSearch>

Response Parameters

Name
Description
Type
Parent
Jobcount
Count of the search results
String
Empty Cell
Jobs
The list of job postings resulting from this search
List of Objects
Empty Cell
JvID
ID for this job posting
String
Jobs
JobTitle
Job title
String
Jobs
Company
Company posting this job
String
Jobs
AccquisitionDate
Acquisition date and time for this job posting at NLX, in UTC (universal coordinated time). Consider converting to your local time zone.
String
Jobs
URL
URL at the company for this posting
String
Jobs
Location
Geographic location of this job
String
Jobs
Fc
If the company posting this job is a federal contractor, Fc is True; otherwise, Fc is False.
String
Jobs
Locations
Locations that are represented in the search results; included in response if showFilters request parameter is set to True
List of Objects
Empty Cell
LocationName
Location name
String
Locations
LocationCount
Number of results in this location
String
Locations
LocationValue
Coming soon. Updated version of response parameter LocationName. Works better for location names that include special characters.
String
Locations
Companies
Companies that are represented in the search results; included in response if showFilters request parameter is set to True
List of Objects
Empty Cell
CompanyName
Company name; can be used as a filter in a subsequent search
String
Companies
JobCount
Number of results in this company
String
Companies
CompanyId
Company ID; obsolete
String
Companies
CompanyValue
Coming soon. Updated version of response parameter CompanyName. Works better for company names that include special characters.
String
Companies
JobsKeywordLocations
Information about the request
Object
Empty Cell
Keyword
Keyword (search term)
String
JobsKeywordLocations
Location
Location given in the request
String
JobsKeywordLocations
IsValidLocation
Is the location valid?
Boolean
JobsKeywordLocations
Radius
Radius
String
JobsKeywordLocations
StartRow
Start Row
String
JobsKeywordLocations
EndRow
End Row
String
JobsKeywordLocations
IsCode
Is keyword (search term) an occupation code? 
Boolean
JobsKeywordLocations
Title
If keyword (search term) is an occupation code, then this parameter is the corresponding occupation title
String
JobsKeywordLocations
LocationState
Full name of the state searched, even if the request parameter was abbreviated
String
JobsKeywordLocations
Message
Error Validation Message
String
JobsKeywordLocations

Errors

Error/Status Code Description
 200
OK / Success. The request went through successfully and there is a response body.
 400
Bad Request (Request was invalid or missing parameters)
 401    
Unauthorized. This error occurs specifically when authentication is required and has failed or has not yet been provided correctly. (ex: Invalid API Token)
 404
This error will be shown in two scenarios 1) Not found - (An error occurred) and 2) Not found - (No data available)
 500
Internal Server Error. This error will occur when there is something critically wrong in the API call.