Banner: Web API: List Occupations by Keyword

Web API: List Occupations by Keyword

List Occupations by Keyword

The 'List Occupations by Keyword' API enables developers to query and retrieve a list of occupations (codes, titles, and descriptions) from a keyword string. A complementary API provides details about O*NET occupations.

About this data

The API provides search results for an occupation based on a keyword entered. The results consist of occupations in any of four different occupation taxonomies:  

(1) the Occupational Information Network (O*NET) taxonomy created by the Department of Labor for cross-agency use by federal, state and local government entities; 

(2) Standard Occupational Classification (SOC) from BLS; 

(3) slight variation on SOC used by BLS Occupational Employment and Wage Statistics (OEWS) program when they publish wage data; 

(4) slight variation on SOC used by BLS Employment Projections program when they publish employment projections. 

Similar information is used in the CareerOneStop Occupation Profile. You can also find information about the data here.

Resource URL

https://api.careeronestop.org/v1/occupation/{userId}/{keyword}/{dataLevelOnly}/{startRecord}/{limitRecord}

Example Code

using System;

using System.Net.Http;

using System.Net.Http.Headers;

using System.Threading.Tasks;

namespace CareerOneStopAPISample

{

    class Program

    {

        static void Main(string[] args)

        {

            CreateRequest().Wait();

        }

        private static async Task CreateRequest()

        {

   

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

            {

                Path = "/v1/occupation/{userId}/{keyword}/{dataLevelOnly}/{startRecord}/{limitRecord}"

            };

           

            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/occupation/{userId}/{keyword}/{dataLevelOnly}/{startRecord}/{limitRecord}")

        .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 services registration process
userId
String
Required
This value is the unique UserID provided during the CareerOneStop web services registration process
keyword
String
Required
Keyword or O*NET code. O*NET codes may be in format ##-####.## or ########. SOC, 
OES, and MAT codes may be in format ###### or ##-####.
dataLevelOnly
String
Required If Y or Yes, and if searchBy is onet, then the response will include only data-level O*NET occupations associated with this occupation, if any; the response will exclude non-data-level occupations. FFI: https://www.onetcenter.org/taxonomy.html#latest
startRecord
Integer
Required
The number of records to skip before returning records. To start at the beginning, use 0.
limitRecord
Integer
Required
This value is the maximum number of results to be returned by web service. 
dataSetType 
 
Optional 
Describes the way the search should be implemented.
0 (default value) = search flexibly, by code if search term is a valid, complete occupation code, else by keyword.
Code = search only by code. If search term is a title, then the search is performed on corresponding code. Keyword may be a partial code; the API returns occupations where there's a match, starting in first or third position. For example, if you search for '1011', results include 11-1011, 13-1011, and others. If dataSetType is code, and the keyword is not a valid occupation code or title, then the call generates an error.
Title = search only by keyword; if search term is a code, then the search is performed on the corresponding title used as the search term.
searchBy  
 
Optional 
Describes the taxonomy from which matches are selected and returned by this API call.
onet (default value) = returns O*NET occupations
soc = returns SOC occupations
socoes = returns occupations used in wage data, from BLS Occupational Employment and Wage Statistics (OEWS) program
socmat = returns occupations used in national employment matrix, from BLS Employment Projections program

Response Structure

{

  "RecordCount": 18,

  "DidYouMean": "",

  "AutoCorrection": "",

 "Request": {

      "InputOccupation": "nurse", 

      "InputOccupationCode": "", 

      "InputOccupationTitle": "" 

    },

  "OccupationList": [

    {

      "OnetTitle": "Informatics Nurse Specialists",

      "OnetCode": "15-1121.01",

      "OccupationDescription": "Apply knowledge of nursing and informatics to assist in the design, development, and ongoing modification of computerized health care systems. May educate staff and assist in problem solving to promote the implementation of the health care system."

    },

    {

      "OnetTitle": "Registered Nurses",

      "OnetCode": "29-1141.00",

      "OccupationDescription": "Assess patient health problems and needs, develop and implement nursing care plans, and maintain medical records. Administer nursing care to ill, injured, convalescent, or disabled patients. May advise patients on health maintenance and disease prevention or provide case management. Licensing or registration required."

    },

    {

      "OnetTitle": "Critical Care Nurses",

      "OnetCode": "29-1141.03",

      "OccupationDescription": "Provide advanced nursing care for patients in critical or coronary care units."

    },

    {

      "OnetTitle": "Acute Care Nurses",

      "OnetCode": "29-1141.01",

      "OccupationDescription": "Provide advanced nursing care for patients with acute conditions such as heart attacks, respiratory distress syndrome, or shock. May care for pre- and post-operative patients or perform advanced, invasive diagnostic or therapeutic procedures."

    },

    {

      "OnetTitle": "Advanced Practice Psychiatric Nurses",

      "OnetCode": "29-1141.02",

      "OccupationDescription": "Provide advanced nursing care for patients with psychiatric disorders. May provide psychotherapy under the direction of a psychiatrist."

    },

    {

      "OnetTitle": "Nurse Practitioners",

      "OnetCode": "29-1171.00",

      "OccupationDescription": "Diagnose and treat acute, episodic, or chronic illness, independently or as part of a healthcare team. May focus on health promotion and disease prevention. May order, perform, or interpret diagnostic tests such as lab work and x rays. May prescribe medication. Must be registered nurses who have specialized graduate education."

    },

    {

      "OnetTitle": "Clinical Nurse Specialists",

      "OnetCode": "29-1141.04",

      "OccupationDescription": "Plan, direct, or coordinate the daily patient care activities in a clinical practice. Ensure adherence to established clinical policies, protocols, regulations, and standards."

    },

    {

      "OnetTitle": "Licensed Practical and Licensed Vocational Nurses",

      "OnetCode": "29-2061.00",

      "OccupationDescription": "Care for ill, injured, or convalescing patients or persons with disabilities in hospitals, nursing homes, clinics, private homes, group homes, and similar institutions. May work under the supervision of a registered nurse. Licensing required."

    },

    {

      "OnetTitle": "Nurse Anesthetists",

      "OnetCode": "29-1151.00",

      "OccupationDescription": "Administer anesthesia, monitor patient's vital signs, and oversee patient recovery from anesthesia. May assist anesthesiologists, surgeons, other physicians, or dentists. Must be registered nurses who have specialized graduate education."

    },

    {

      "OnetTitle": "Nurse Midwives",

      "OnetCode": "29-1161.00",

      "OccupationDescription": "Diagnose and coordinate all aspects of the birthing process, either independently or as part of a healthcare team. May provide well-woman gynecological care. Must have specialized, graduate nursing education."

    }

  ],

  "SocOccupationList": "null",

  "SocOesOccupationList": "null",

  "SocMatOccupationList": "null",

}
<OccupationsList xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/XPAND.CareerOneStop.WebApi.ViewModels">

  <AutoCorrection />

  <DidYouMean />

  <OccupationList>

    <OccupationDetail>

      <OccupationDescription>Apply knowledge of nursing and informatics to assist in the design, development, and ongoing modification of computerized health care systems. May educate staff and assist in problem solving to promote the implementation of the health care system.</OccupationDescription>

      <OnetCode>15-1121.01</OnetCode>

      <OnetTitle>Informatics Nurse Specialists</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Assess patient health problems and needs, develop and implement nursing care plans, and maintain medical records. Administer nursing care to ill, injured, convalescent, or disabled patients. May advise patients on health maintenance and disease prevention or provide case management. Licensing or registration required.</OccupationDescription>

      <OnetCode>29-1141.00</OnetCode>

      <OnetTitle>Registered Nurses</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Provide advanced nursing care for patients in critical or coronary care units.</OccupationDescription>

      <OnetCode>29-1141.03</OnetCode>

      <OnetTitle>Critical Care Nurses</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Provide advanced nursing care for patients with acute conditions such as heart attacks, respiratory distress syndrome, or shock. May care for pre- and post-operative patients or perform advanced, invasive diagnostic or therapeutic procedures.</OccupationDescription>

      <OnetCode>29-1141.01</OnetCode>

      <OnetTitle>Acute Care Nurses</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Provide advanced nursing care for patients with psychiatric disorders. May provide psychotherapy under the direction of a psychiatrist.</OccupationDescription>

      <OnetCode>29-1141.02</OnetCode>

      <OnetTitle>Advanced Practice Psychiatric Nurses</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Diagnose and treat acute, episodic, or chronic illness, independently or as part of a healthcare team. May focus on health promotion and disease prevention. May order, perform, or interpret diagnostic tests such as lab work and x rays. May prescribe medication. Must be registered nurses who have specialized graduate education.</OccupationDescription>

      <OnetCode>29-1171.00</OnetCode>

      <OnetTitle>Nurse Practitioners</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Plan, direct, or coordinate the daily patient care activities in a clinical practice. Ensure adherence to established clinical policies, protocols, regulations, and standards.</OccupationDescription>

      <OnetCode>29-1141.04</OnetCode>

      <OnetTitle>Clinical Nurse Specialists</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Care for ill, injured, or convalescing patients or persons with disabilities in hospitals, nursing homes, clinics, private homes, group homes, and similar institutions. May work under the supervision of a registered nurse. Licensing required.</OccupationDescription>

      <OnetCode>29-2061.00</OnetCode>

      <OnetTitle>Licensed Practical and Licensed Vocational Nurses</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Administer anesthesia, monitor patient's vital signs, and oversee patient recovery from anesthesia. May assist anesthesiologists, surgeons, other physicians, or dentists. Must be registered nurses who have specialized graduate education.</OccupationDescription>

      <OnetCode>29-1151.00</OnetCode>

      <OnetTitle>Nurse Anesthetists</OnetTitle>

    </OccupationDetail>

    <OccupationDetail>

      <OccupationDescription>Diagnose and coordinate all aspects of the birthing process, either independently or as part of a healthcare team. May provide well-woman gynecological care. Must have specialized, graduate nursing education.</OccupationDescription>

      <OnetCode>29-1161.00</OnetCode>

      <OnetTitle>Nurse Midwives</OnetTitle>

    </OccupationDetail>

  </OccupationList>

  <RecordCount>18</RecordCount>

  <Request> 

      <InputOccupation>nurse</InputOccupation> 

      <InputOccupationCode/> 

      <InputOccupationTitle/> 

    </Request>

  <SocMatOccupationList/>

  <SocOccupationList />

  <SocOesOccupationList />

</OccupationsList>

Response Parameters

Name
Description
Type
Parent
RecordCount
Record Count
Number
Empty Cell
DidYouMean
Did You Mean
String
Empty Cell
AutoCorrection
Auto Corrections
String
Empty Cell
Request
Info about your API request
Object
Empty Cell
InputOccupation
The keyword by which you are searching
String
Request
InputOccupationCode
If keyword is an occupation, then this is the corresponding occupation code. Null otherwise. 
String
Request
InputOccupationTitle
If keyword is an occupation, then this is the corresponding occupation title. Null otherwise. 
String
Request
OccupationList
Matching Occupations. This object contains info about all matching occupations, in the taxonomy you requested. 
List of objects
Empty Cell
OnetTitle
Title in the taxonomy you requested, which may or may not be O*NET
String
OccupationList
OnetCode
Code in the taxonomy you requested, which may or may not be O*NET
String
OccupationList
OccupationDescription
Occupation Description in the taxonomy you requested, which may or may not be O*NET
String
OccupationList
SocOccupationList
Matching SOC occupations, if you requested SOC
List of objects
 
Title
Title of SOC occupation
String
Soc OccupationList
Code
Code of SOC occupation
String
Soc OccupationList
OccupationDescription
Description of SOC occupation
String
SocOccupationList
SocOesOccupationList
Matching OES occupations, if you requested OES
List of objects
 
Title
Title of OES occupation
String
SocOesOccupationList
Code
Code of OES occupation
String
socOesOccupationList
OccupationDescription
Never populated in this API
String
SocOesOccupationList
SocMatOccupationList
Matching occupations from the National Employment Matrix (MAT), if you requested MAT
List of objects
 
Title
Title of MAT occupation
String
SocMatOccupationList
Code
Code of MAT occupation
String
SocMatOccupationList
Occupation Description Never populated in this API String SocMatOccupationList

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.