List jobs

List jobs

List jobs

'List Jobs' is an API that enables developers to retrieve job postings for a specific keyword or an O*NET occupation code.  The returned list object contains the number of jobs available in the area as reported by the National Labor Exchange. The API provides search results based on keyword entered. The search utilizes 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. For more information about the data, click here.

Resource URL

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

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
This value is the search term
location
String Required This value accepts a city, state (Chicago, IL) or state (IL) or ZIP code (61299). Use the numeral 0 for a nationwide search.
radius
String Required
The radius, in miles of the job opportunities search area. Applies to ZIP code searches only.
days Integer Required Number of days to go back to get the job postings.
sortColumns
String Required

This value is for sorting the columns. Valid values are: jobtitle, company, location, accquisitiondate. Default value '0' sorts by relevance to the search term.

sortOrder
String Required

Use this parameter to set the ordering of the results. Valid values are ASC, DESC.

startRow
Integer
Required
Specifies the start row. Allowed values are 1 to 500.
pageSize
Integer
Required
This value is the number of results to be returned by Web API.
companyName
String
Optional
The filter value for the company who 'owns' the job.
locationFilter
String
Optional
The filter value for the location who 'owns' the job.
showFilters
String
Optional
The flag value to show company and location filters for the jobs.

Response Structure

{

  "Jobcount": "3173",

  "Jobs": [

    {

      "JvId": "CFB69487E3524B6E83E6A6BB05F7895D206",

      "JobTitle": "Registered Nurse (Nurse Educator)",

      "Company": "Veterans Affairs, Veterans Health Administration",

      "AccquisitionDate": "2016-10-18 5:15 PM",

      "URL": "http://my.jobs/CFB69487E3524B6E83E6A6BB05F7895D206",

      "Location": "Richmond, Virginia",

      "Fc": "False"

    },

    {

      "JvId": "2015B35F4CD746C3BA1A96132D47FDE6206",

      "JobTitle": "Registered Nurse (Nurse Educator)",

      "Company": "Veterans Affairs, Veterans Health Administration",

      "AccquisitionDate": "2016-10-18 5:10 PM",

      "URL": "http://my.jobs/2015B35F4CD746C3BA1A96132D47FDE6206",

      "Location": "Emporia, Virginia",

      "Fc": "False"

    },

    {

      "JvId": "76B91CD51D9547D08210B92B3083BC04206",

      "JobTitle": "REGISTERED NURSE",

      "Company": "Veterans Affairs, Veterans Health Administration",

      "AccquisitionDate": "2016-10-18 5:13 PM",

      "URL": "http://my.jobs/76B91CD51D9547D08210B92B3083BC04206",

      "Location": "Huntington, West Virginia",

      "Fc": "False"

    },

    {

      "JvId": "202FB5D9891E4B2B8F967EB3537B9622206",

      "JobTitle": "Registered Nurse",

      "Company": "West Virginia Employer",

      "AccquisitionDate": "2016-10-11 7:10 PM",

      "URL": "http://my.jobs/202FB5D9891E4B2B8F967EB3537B9622206",

      "Location": "Martinsburg, West Virginia",

      "Fc": "False"

    },

    {

      "JvId": "49FA4E0CF17A4F5C885AD7EC5B9FB14B206",

      "JobTitle": "Registered Nurse",

      "Company": "Genesis Staffing Services",

      "AccquisitionDate": "2016-9-27 7:11 PM",

      "URL": "http://my.jobs/49FA4E0CF17A4F5C885AD7EC5B9FB14B206",

      "Location": "Charles Town, West Virginia",

      "Fc": "False"

    },

    {

      "JvId": "8B232D3028694D73AD3F1DEAE0FA350B206",

      "JobTitle": "Registered Nurse",

      "Company": "HCA, Hospital Corporation of America",

      "AccquisitionDate": "2016-10-18 6:38 PM",

      "URL": "http://my.jobs/8B232D3028694D73AD3F1DEAE0FA350B206",

      "Location": "Low Moor, Virginia",

      "Fc": "False"

    },

    {

      "JvId": "83B5810CE31D43079521A0F419E3D2AB206",

      "JobTitle": "Director of Nursing",

      "Company": "Commonwealth Of Virginia",

      "AccquisitionDate": "2016-10-6 2:05 AM",

      "URL": "http://my.jobs/83B5810CE31D43079521A0F419E3D2AB206",

      "Location": "Virginia",

      "Fc": "False"

    },

    {

      "JvId": "F4E54DD4221D4BC6B982AFA7B9B9340E206",

      "JobTitle": "Nursing Supervisor",

      "Company": "Virginia State Government",

      "AccquisitionDate": "2016-10-19 6:10 AM",

      "URL": "http://my.jobs/F4E54DD4221D4BC6B982AFA7B9B9340E206",

      "Location": "Roanoke, Virginia",

      "Fc": "False"

    },

    {

      "JvId": "A931EE4FA6434210AE9C77B1C4D57EB5206",

      "JobTitle": "Registered Nurse",

      "Company": "Virginia Tech",

      "AccquisitionDate": "2016-10-4 8:31 PM",

      "URL": "http://my.jobs/A931EE4FA6434210AE9C77B1C4D57EB5206",

      "Location": "Blacksburg, Virginia",

      "Fc": "False"

    },

    {

      "JvId": "E374084E0F5D42929C64FE9B28441A5E206",

      "JobTitle": "Registered Nurse",

      "Company": "HCA, Hospital Corporation of America",

      "AccquisitionDate": "2016-10-18 6:44 PM",

      "URL": "http://my.jobs/E374084E0F5D42929C64FE9B28441A5E206",

      "Location": "Falls Church, Virginia",

      "Fc": "False"

    }

  ],

  "JobsKeywordLocations": {

    "Keyword": "nurse",

    "Location": "\"VA\"",

    "Radius": "0",

    "StartRow": "0",

    "EndRow": "10"

  },

}
<JobSearch 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>3173</Jobcount>

  <Jobs>

    <Job>

      <AccquisitionDate>2016-10-18 5:15 PM</AccquisitionDate>

      <Company>Veterans Affairs, Veterans Health Administration</Company>

      <Fc>False</Fc>

      <JobTitle>Registered Nurse (Nurse Educator)</JobTitle>

      <JvId>CFB69487E3524B6E83E6A6BB05F7895D206</JvId>

      <Location>Richmond, Virginia</Location>

      <URL>http://my.jobs/CFB69487E3524B6E83E6A6BB05F7895D206</URL>

     </Job>

    <Job>

      <AccquisitionDate>2016-10-18 5:10 PM</AccquisitionDate>

      <Company>Veterans Affairs, Veterans Health Administration</Company>

      <Fc>False</Fc>

     <JobTitle>Registered Nurse (Nurse Educator)</JobTitle>

      <JvId>2015B35F4CD746C3BA1A96132D47FDE6206</JvId>

      <Location>Emporia, Virginia</Location>

      <URL>http://my.jobs/2015B35F4CD746C3BA1A96132D47FDE6206</URL>

    </Job>

    <Job>

      <AccquisitionDate>2016-10-11 7:10 PM</AccquisitionDate>

      <Company>West Virginia Employer</Company>

      <Fc>False</Fc>

      <JobTitle>Registered Nurse</JobTitle>

      <JvId>202FB5D9891E4B2B8F967EB3537B9622206</JvId>

      <Location>Martinsburg, West Virginia</Location>

      <URL>http://my.jobs/202FB5D9891E4B2B8F967EB3537B9622206</URL>

    </Job>

    <Job>

      <AccquisitionDate>2016-10-18 5:13 PM</AccquisitionDate>

      <Company>Veterans Affairs, Veterans Health Administration</Company>

      <Fc>False</Fc>

      <JobTitle>REGISTERED NURSE</JobTitle>

      <JvId>76B91CD51D9547D08210B92B3083BC04206</JvId>

      <Location>Huntington, West Virginia</Location>

      <URL>http://my.jobs/76B91CD51D9547D08210B92B3083BC04206</URL>

    </Job>

    <Job>

      <AccquisitionDate>2016-10-19 6:10 AM</AccquisitionDate>

      <Company>Virginia State Government</Company>

      <Fc>False</Fc>

      <JobTitle>Nursing Supervisor</JobTitle>

      <JvId>F4E54DD4221D4BC6B982AFA7B9B9340E206</JvId>

      <Location>Roanoke, Virginia</Location>

      <URL>http://my.jobs/F4E54DD4221D4BC6B982AFA7B9B9340E206</URL>

    </Job>

    <Job>

      <AccquisitionDate>2016-9-27 7:11 PM</AccquisitionDate>

      <Company>Genesis Staffing Services</Company>

      <Fc>False</Fc>

      <JobTitle>Registered Nurse</JobTitle>

      <JvId>49FA4E0CF17A4F5C885AD7EC5B9FB14B206</JvId>

      <Location>Charles Town, West Virginia</Location>

      <URL>http://my.jobs/49FA4E0CF17A4F5C885AD7EC5B9FB14B206</URL>

     </Job>

    <Job>

      <AccquisitionDate>2016-10-18 6:38 PM</AccquisitionDate>

      <Company>HCA, Hospital Corporation of America</Company>

      <Fc>False</Fc>

      <JobTitle>Registered Nurse</JobTitle>

      <JvId>8B232D3028694D73AD3F1DEAE0FA350B206</JvId>

      <Location>Low Moor, Virginia</Location>

      <URL>http://my.jobs/8B232D3028694D73AD3F1DEAE0FA350B206</URL>

     </Job>

    <Job>

      <AccquisitionDate>2016-10-6 2:05 AM</AccquisitionDate>

      <Company>Commonwealth Of Virginia</Company>

      <Fc>False</Fc>

      <JobTitle>Director of Nursing</JobTitle>

       <JvId>83B5810CE31D43079521A0F419E3D2AB206</JvId>

      <Location>Virginia</Location>

      <URL>http://my.jobs/83B5810CE31D43079521A0F419E3D2AB206</URL>

    </Job>

    <Job>

      <AccquisitionDate>2016-10-17 5:39 PM</AccquisitionDate>

      <Company>VCU Health System</Company>

      <Fc>False</Fc>

      <JobTitle>Clinical Nurse</JobTitle>

      <JvId>3DE78B4F2FFD434B96A75E30653E36EE206</JvId>

      <Location>Richmond, Virginia</Location>

      <URL>http://my.jobs/3DE78B4F2FFD434B96A75E30653E36EE206</URL>

    </Job>

    <Job>

      <AccquisitionDate>2016-10-4 8:31 PM</AccquisitionDate>

      <Company>Virginia Tech</Company>

      <Fc>False</Fc>

      <JobTitle>Registered Nurse</JobTitle>

      <JvId>A931EE4FA6434210AE9C77B1C4D57EB5206</JvId>

      <Location>Blacksburg, Virginia</Location>

      <URL>http://my.jobs/A931EE4FA6434210AE9C77B1C4D57EB5206</URL>

    </Job>

  </Jobs>

  <JobsKeywordLocations>

    <EndRow>10</EndRow>

    <Keyword>nurse</Keyword>

    <Location>"VA"</Location>

    <Radius>0</Radius>

    <StartRow>0</StartRow>

  </JobsKeywordLocations>  

</JobSearch>

Response Parameters

Name
Description
Type
Parent
Jobcount
Job Count
String
Empty Cell
Jobs
The whole list of jobs
Object
Empty Cell
Job
One job posting
Object
Jobs
JvID
ID for this job
String
Job
JobTitle
Job Title
String
Job
Company
company
String
Job
AccquisitionDate
Acquisition Date
String
Job
URL
URL
String
Job
Location
Location
String
Job
Fc
If the employer associated with this job posting a federal contractor, Fc is True; otherwise, Fc is False.
String
Job
JobsKeywordLocations
The request parameters, plus count of all jobs matching this request
Object
Empty Cell
Keyword
Keyword
String
JobsKeywordLocations
Location
Location
String
JobsKeywordLocations
IsValidLocation
IsValidLocation
String
JobsKeywordLocations
Radius
Radius
String
JobsKeywordLocations
StartRow
Start Row
String
JobsKeywordLocations
EndRow
End Row
String
JobsKeywordLocations
IsCode
IsCode
String
Empty Cell
Title
Title
String
Empty Cell
LocationState
LocationState
String
Empty Cell

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.