Reference Manual (API Version 2.0)

Migrating from version 1.9

O*NET Web Services version 2 is a major upgrade which incorporates new features from O*NET OnLine and My Next Move. In addition, it simplifies the authentication process, streamlines some JSON responses for easier access, updates Database Services, introduces OpenAPI definitions, and serves as the basis for future releases and feature additions.

Web Services users who sign up before the end of the version 2.0 beta period may continue to use version 1.9 for their projects, but future enhancements and new features will be added exclusively to version 2.

Should I migrate?

• If you do not plan to extend your existing application, you may continue to use version 1.9 without any changes to your application code.
• If you make limited enhancements to your application, you may continue to use version 1.9 in your existing code, and build new features using version 2. You can obtain a version 2 API key for your existing Web Services project in the My Account section. In your code, we recommend approaching version 2 as a new third-party web service, and treating versions 1 and 2 like two separate sources of information.
• If you plan to extend and revise your application over time, upgrading to version 2 throughout your code will provide a consistent base for future development. Going forward, you will not need to maintain code for two authentication systems or worry about which features are only present in version 2.

Note: All users, even those who continue to use version 1.9, should review the list of deprecated features. If your application makes use of any of these features, we recommend you consider alternate sources for the impacted information. Some deprecated features have supported replacements in version 2.

How do I migrate?

To covert your existing applications to O*NET Web Services version 2.0, you need to take three main steps:

1. Obtain a version 2 API key
2. Update URLs and HTTP headers in your requests
3. Handle updated response structures in your code

After these steps are complete, you can optionally enhance your application by taking advantage of new APIs in version 2.0.

Obtain a version 2 API key

In the My Account section, click the "Add a new API key" button under the "API keys" section of your project. You will use the generated key in the next step.

Update URLs and HTTP headers

If your application is based on the official sample code on GitHub , update to the version 2 sample code , and provide your version 2 API key in place of your version 1 username and password. Otherwise, follow the steps below.

Update the base URL for all services, which has changed in version 2. For example, to call the My Next Move career search:

• Version 1.9: https://services.onetcenter.org/ws/mnm/search?keyword=architect
• Version 2.0: https://api-v2.onetcenter.org/mnm/search?keyword=architect

Add an X-API-Key header to all requests. The value of this header is the key you generated in the step above. For more info, see the Authentication documentation.

Remove any Authentication header, HTTP Basic authentication credentials, or client query string parameters sent in your requests. In version 2, these methods are replaced with API keys.

Remove any Accept headers sent in your requests. Version 2 always sends responses in JSON format, so you don't need to specifically ask for JSON. If you are currently parsing XML requests, you will also need to update your code to handle JSON responses instead.

Handle updated response structures

Pagination links have been simplified in version 2. If your code navigates paged results using the link object, instead use the top-level prev and next properties. If you construct pagination links directly using the start and end parameters, no changes are needed. For more info, see the Pagination section.

While most services retain the same basic response structure, changes have been made to reduce nesting, and to improve clarity and consistency. For example, in the OnLine Knowledge details report, read the first importance score from response.element[0].importance instead of response.element[0].score.value. We recommend you review the documentation for the services you use, or use our OpenAPI document to generate or validate your response-handling code.

Review the list of features removed from version 2, and update your application to rewrite any impacted areas. Some removed features have been replaced with similar replacements.

New features in version 2

O*NET Web Services version 2 provides access to the latest features in O*NET OnLine and My Next Move, and also adds services for long-standing functionality not present in version 1. Highlights include:

My Next Move services

• Browse careers by cluster
• Careers sorted by Interest

O*NET OnLine services

• Advanced searches:
  • Job duties custom list
  • Professional associations search
  • Related activities search
  • Soft skills custom list
  • Technology skills search
• Browse by O*NET Data for all domains shown in OnLine, including occupation listings based on multiple interests or work values
• Enhancements to the Hot Technology browse and occupation reports, including In Demand technology skills

Database services

• Download links added to the Table column information service, for automated monitoring and download of new O*NET Database releases
• Links to the corresponding Data Dictionary reference for each table, for easier discovery of a table's structure and purpose

OpenAPI definition

Version 2 services are formally described using OpenAPI, so you can generate code or explore our APIs using compatible tools. For more info, see the OpenAPI section.

Features removed from version 2

Version 1.9 includes information and features no longer included in the current versions of O*NET websites. While the service endpoints will remain accessible under this legacy version, these features are deprecated and the returned results may be empty or incomplete. All users should consider alternate sources of information for their ongoing applications.

• Green occupation tags and searches – for newer research on environmentally friendly activities, see the O*NET Resource Center's Green Topics page.
• Apprenticeship tags on My Next Move careers – for apprenticeship opportunities across a range of careers, see Apprenticeship.gov .
• Career videos search – the vast majority of My Next Move careers are accompanied by videos. For more information on career videos, see CareerOneStop .
• Related DWA search – replaced by the Related activities search.
• Related Task search – replaced by the Job duties custom list.
• Tools & Technology search – replaced by the Technology skills search.

In this section

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