Reference Manual (API Version 2.0)

Overview

O*NET Web Services uses a RESTful web services API. All resources are accessed with the GET method and return data in JSON format. Access is limited to registered developers; you can obtain access credentials and instructions by signing up for the developer program. Before you sign up, you can try our interactive demo to see the API in action. The services currently use the O*NET 29.2 Database and are kept up to date as new versions are released.

Comparison of features by category

Each category of O*NET Web Services corresponds to a specific product or application in the O*NET family. These products are tailored to different audiences and use cases, as outlined in the table below.

Sample code

Code samples, including utility libraries and full working examples, are available on GitHub for the following languages:

• Client-side JavaScript
• C#
• NodeJS
• Perl
• PHP
• Python
• Ruby

These samples demonstrate how to use your Web Services API key, how to check for errors, and how to parse JSON results. Each language includes a full working demo of the occupation keyword search.

Authentication

All requests must be accompanied by an X-API-Key header. API keys can be generated or revoked in the My Account section. Multiple keys can be active for a single project, so you can fully deploy a newer key before revoking an old one. The key must be provided in an HTTP header; keys are not accepted in the query string or in a POST body. (All requests must be made with the GET method; POST requests will be denied.)

Error handling

• Example

Error conditions in the web services API are indicated with HTTP status codes. When a client calls a service with unexpected parameters, an error response may be returned, along with a 422 status code. This can happen when:

• A required parameter (such as the keyword parameter in the Search careers service) is not provided, or a parameter was not formatted correctly.
• Information is requested for a non-existent or obsolete O*NET-SOC code.
• No data is available for a particular career or parameter. For example, no Knowledge data is available for Legislators.

As with any web service, clients should also be prepared to handle other HTTP errors, such as 404 or 500. Only errors with a 422 code are guaranteed to contain a JSON error response.

Rate limits

O*NET Web Services are provided on a “best-effort” basis, and no guarantee of availability is made. When availability is limited, requests may receive a 429 error code in response. Your application should detect this response and delay at least 200 milliseconds before retrying the request.

We do not currently impose a maximum rate limit, but we provide guidance for per-second and per-day usage rates in our Terms of Service. For batch processes, please target these rates by building in appropriate delays in your application. For real-time applications, if your expected request volume exceeds these rates, please consider options such as caching responses to common requests: most O*NET data sources are updated on a quarterly or annual basis. If you have additional questions or concerns, please contact O*NET Customer Service (onet@onetcenter.org).

Pagination

Many services return a paged list of results, with only a subset returned by default. In these cases, the top level response will include the following fields:

• start – the index of the first result returned. The first index is 1.
• end – the index of the last result returned. This will be 0 if no results match the given search or page criteria.
• total – the total number of results available for this request. The total will be 0 if no results match the given search criteria.
• prev – if start is greater than 1, this field links to the previous page of results. This field is not present in the first page of results.
• next – if end is greater than 0 but less than total, this field links to the next page of results. This field is not present in the last page of results.

For paged services, you can jump directly to a desired index by setting the start query parameter. You can override the service’s default page size by setting the end parameter to the desired last index. The maximum page size is 2000, so allowed values for end range from start + 0 to start + 1999.

Documentation layout

The documentation for each service has the following layout:

• URL bar – lists the full URL of the service. It may contain placeholders for dynamic values, such as occupation codes or search strings, which are highlighted in italics.
• A tabbed section with up to three tabs:
  • Example – a sample of the response returned by this service. Some details may be omitted for clarity.
  • Model – a table of every field in the response, along with the type of data (number, string, array, etc.). Optional fields are marked; non-optional fields are always present.
  • Inputs – a listing of the input parameters which can be provided in either the URL or in the query string. If there are no input parameters, this tab is not present.
• Detail links – links to the Interactive Demo section, where you can see the complete response and change the query parameters, and also to an example of the data within an O*NET website (where applicable).
• Description – text explaining the purpose of the service, and explaining any special features of the query or response. Intended as a supplement to the full reference in the Model and Inputs tabs.

OpenAPI definition

O*NET Web Services APIs are defined in an OpenAPI 3.1 document, for use with code generation tools or other utilities to aid in development. If you are new to OpenAPI, many compatible tools can be found in the OpenAPI.Tools directory.

Download OpenAPI definition (JSON)

In this section

• Getting started
  • Overview
  • Migrating from version 1.9
  • Account management
  • Version information