Compare Salaries by Location Web API

your source for career exploration, training & jobs

Compare Salaries by Locations API

The 'Compare by Locations' API enables developers to input from one to five occupations, and from one to five locations, in order to retrieve and compare data about the wages for those occupations in those locations. The API accepts O*NET and SOC occupation codes and titles.

About this data

The Compare Salaries tool demonstrates how this API can be used. For more information about the data, please visit the Compare Salaries help page.

Resource URL

https://api.careeronestop.org/v1/comparesalaries/{userId}/wageloc?keyword={keyword}&location={location}&sortColumns={sortColumns}&sortOrder={sortOrder}&sortBy={sortOrder}&enableMetaData={enableMetaData}

Try this Web API

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/comparesalaries/{userId}/wageloc?keyword={keyword}&location={location}&sortColumns={sortColumns}&sortOrder={sortOrder}&sortBy={sortOrder}&enableMetaData={enableMetaData}"

            };

           

            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/comparesalaries/{userId}/wageloc?keyword={keyword}&location={location}&sortColumns={sortColumns}&sortOrder={sortOrder}&sortBy={sortOrder}&enableMetaData={enableMetaData}")

        .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	Yes	This value is the unique API Token provided during the CareerOneStop Web API registration process.
userId	String	Yes	This value is the unique UserID provided during the CareerOneStop Web API registration process.
keyword	String	Yes	Occupations to compare. Could be one or more occupations (O*NET or SOC title or code) separated by \| ("pipe" or "bar"). Example: 17-1011\|29-1171.
location	String	Yes	Locations to compare. Could be city and state (example: Chicago, IL), state (IL), or zipcode (60050); or multiple locations separated by a \| ('pipe" or "bar"). Example: Chicago, IL \| Tampa, FL.
sortColumns	String	Yes	This is the column by which the data should be sorted. Acceptable values include: 0 - LT (default) LT - Location title LW - Low wage MW - Median wage HW - High wage
sortDirections	String	Yes	Sort Direction Acceptable values include: 0 - Ascending (default) ASC - Ascending DESC - Descending
sortBy	String	Yes	sortBy Acceptable values include: 0 - Hourly (default) Hourly Annual
enableMetaData	boolean	Optional	Use this parameter to determine whether to include MetaData in the response. True- Include metadata (default) False - exclude metadata

Response Structure

JSON
XML

{
  "ErrorMessage": null,
  "InValidOccupations": null,
  "InValidLocations": null,
  "RecordCount": 2,
  "Keyword": "17-1011.00|29-1171.00",
  "Location": "va|ca",
  "sortColumns": "OT",
  "sortOrder": "ASC",
  "sortBy": "Hourly",
  "OccupationsList": [
    {
      "OccupationName": "Architects, Except Landscape and Naval",
      "OccupationCode": "171011",
      "Request": {
        "InputOccupation": "17-1011.00",
        "InputOccupationCode": "17-1011.00",
        "InputOccupationTitle": "Architects, Except Landscape and Naval"
      },
      "SocInfo": {
        "SocCode": "171011",
        "SocTitle": "Architects, Except Landscape and Naval",
        "SocDescription": "Plan and design structures, such as private residences, office buildings, theaters, factories, and other structural property. Excludes \"Landscape Architects\" and \"Marine Engineers and Naval Architects\"."
      },
      "LocationWageDetails": [
        {
          "LocationName": "California",
          "InputLocation": "ca",
          "WageInfo": [
            {
              "RateType": "Hourly",
              "Pct10": "25.48",
              "Pct25": "32.53",
              "Median": "41.91",
              "Pct75": "55.28",
              "Pct90": "71.03",
              "StFips": "06",
              "Area": "000006",
              "AreaName": "California"
            },
            {
              "RateType": "Annual",
              "Pct10": "52990",
              "Pct25": "67670",
              "Median": "87180",
              "Pct75": "114990",
              "Pct90": "147730",
              "StFips": "06",
              "Area": "000006",
              "AreaName": "California"
            }
          ]
        },
        {
          "LocationName": "Virginia",
          "InputLocation": "va",
          "WageInfo": [
            {
              "RateType": "Hourly",
              "Pct10": "22.69",
              "Pct25": "29.83",
              "Median": "39.92",
              "Pct75": "49.45",
              "Pct90": "61.5",
              "StFips": "51",
              "Area": "000051",
              "AreaName": "Virginia"
            },
            {
              "RateType": "Annual",
              "Pct10": "47200",
              "Pct25": "62050",
              "Median": "83040",
              "Pct75": "102850",
              "Pct90": "127920",
              "StFips": "51",
              "Area": "000051",
              "AreaName": "Virginia"
            }
          ]
        }
      ]
    },
    {
      "OccupationName": "Nurse Practitioners",
      "OccupationCode": "291171",
      "Request": {
        "InputOccupation": "29-1171.00",
        "InputOccupationCode": "29-1171.00",
        "InputOccupationTitle": "Nurse Practitioners"
      },
      "SocInfo": {
        "SocCode": "291171",
        "SocTitle": "Nurse Practitioners",
        "SocDescription": "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."
      },
      "LocationWageDetails": [
        {
          "LocationName": "California",
          "InputLocation": "ca",
          "WageInfo": [
            {
              "RateType": "Hourly",
              "Pct10": "45.65",
              "Pct25": "53.63",
              "Median": "61",
              "Pct75": "74.89",
              "Pct90": "91.87",
              "StFips": "06",
              "Area": "000006",
              "AreaName": "California"
            },
            {
              "RateType": "Annual",
              "Pct10": "94940",
              "Pct25": "111550",
              "Median": "126890",
              "Pct75": "155780",
              "Pct90": "191090",
              "StFips": "06",
              "Area": "000006",
              "AreaName": "California"
            }
          ]
        },
        {
          "LocationName": "Virginia",
          "InputLocation": "va",
          "WageInfo": [
            {
              "RateType": "Hourly",
              "Pct10": "36.7",
              "Pct25": "42.42",
              "Median": "49.27",
              "Pct75": "58.11",
              "Pct90": "64.63",
              "StFips": "51",
              "Area": "000051",
              "AreaName": "Virginia"
            },
            {
              "RateType": "Annual",
              "Pct10": "76330",
              "Pct25": "88220",
              "Median": "102480",
              "Pct75": "120870",
              "Pct90": "134430",
              "StFips": "51",
              "Area": "000051",
              "AreaName": "Virginia"
            }
          ]
        }
      ]
    }
  ],
  "MetaData": {
    "Publisher": "CareerOneStop publishes this API (www.careeronestop.org/Developers/WebAPI/web-api.aspx)",
    "Sponsor": "U.S. Department of Labor, Employment and Training Administration",
    "LastAccessDate": 1578066285,
    "CitationSuggested": "This data is delivered by an API from CareerOneStop, sponsored by U.S. Department of Labor, Employment and Training Administration.  \nwww.careeronestop.org\nSalary data are from U.S. Department of Labor, Bureau of Labor Statistics, Occupational Employment Statistics program (www.bls.gov/oes), May 2018.",
    "DataSource": [
      {
        "DataName": "Wages by occupation",
        "DataSourceName": "U.S. Department of Labor, Bureau of Labor Statistics, Employment Projections program",
        "DataSourceUrl": "https://www.bls.gov/oes/",
        "DataLastUpdate": "7/1/2019",
        "DataVintageOrVersion": "May 2018",
        "DataDescription": "The Occupational Employment Statistics (OES) program produces employment and wage estimates annually for over 800 occupations. These estimates are available for the nation as a whole, for individual states, and for metropolitan and nonmetropolitan areas; national occupational estimates for specific industries are also available."
        "DataSourceCitation": "Salary data are from U.S. Department of Labor, Bureau of Labor Statistics, Occupational Employment Statistics (OES) program, May 2018 (www.bls.gov/oes/)."
      }
    ]
  }
}

<CompareWagesByLocations
xmlns="http://schemas.datacontract.org/2004/07/XPAND.CareerOneStop.WebApi.ViewModels"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ErrorMessage i:nil="true"/>
<InValidLocations
xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" i:nil="true"/>
<InValidOccupations
xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" i:nil="true"/>
<Keyword>17-1011.00|29-1171.00</Keyword>
<Location>va|ca</Location>
<MetaData
xmlns:d2p1="http://schemas.datacontract.org/2004/07/XPAND.CareerOneStop.WebApi.Core.MetaData">
<d2p1:CitationSuggested>This data is delivered by an API from CareerOneStop, sponsored by U.S. Department of Labor, Employment and Training Administration.
www.careeronestop.org
Salary data are from U.S. Department of Labor, Bureau of Labor Statistics, Occupational Employment Statistics program (www.bls.gov/oes), May 2018.</d2p1:CitationSuggested>
<d2p1:DataSource>
<d2p1:MetaDataSource>
<d2p1:DataDescription>The Occupational Employment Statistics (OES) program produces employment and wage estimates annually for over 800 occupations. These estimates are available for the nation as a whole, for individual states, and for metropolitan and nonmetropolitan areas; national occupational estimates for specific industries are also available.</d2p1:DataDescription>
<d2p1:DataLastUpdate>7/1/2019</d2p1:DataLastUpdate>
<d2p1:DataName>Wages by occupation</d2p1:DataName>
<d2p1:DataSourceCitation>Salary data are from U.S. Department of Labor, Bureau of Labor Statistics, Occupational Employment Statistics (OES) program, May 2018 (www.bls.gov/oes/).</d2p1:DataSourceCitation> <d2p1:DataSourceName>U.S. Department of Labor, Bureau of Labor Statistics, Employment Projections program</d2p1:DataSourceName>
<d2p1:DataSourceUrl>https://www.bls.gov/oes/</d2p1:DataSourceUrl>
<d2p1:DataVintageOrVersion>May 2018</d2p1:DataVintageOrVersion> </d2p1:MetaDataSource>
</d2p1:DataSource>
<d2p1:LastAccessDate>1578066357</d2p1:LastAccessDate>
<d2p1:Publisher>CareerOneStop publishes this API (www.careeronestop.org/Developers/WebAPI/web-api.aspx)</d2p1:Publisher>
<d2p1:Sponsor>U.S. Department of Labor, Employment and Training Administration</d2p1:Sponsor>
</MetaData>
<OccupationsList>
<WagesByOccupations>
<LocationWageDetails>
<LocationWageDetails>
<InputLocation>ca</InputLocation>
<LocationName>California</LocationName>
<WageInfo>
<WageDetails>
<Area>000006</Area>
<AreaName>California</AreaName>
<Median>41.91</Median>
<Pct10>25.48</Pct10>
<Pct25>32.53</Pct25>
<Pct75>55.28</Pct75>
<Pct90>71.03</Pct90>
<RateType>Hourly</RateType>
<StFips>06</StFips>
</WageDetails>
<WageDetails>
<Area>000006</Area>
<AreaName>California</AreaName>
<Median>87180</Median>
<Pct10>52990</Pct10>
<Pct25>67670</Pct25>
<Pct75>114990</Pct75>
<Pct90>147730</Pct90>
<RateType>Annual</RateType>
<StFips>06</StFips>
</WageDetails>
</WageInfo>
</LocationWageDetails>
<LocationWageDetails>
<InputLocation>va</InputLocation>
<LocationName>Virginia</LocationName>
<WageInfo>
<WageDetails>
<Area>000051</Area>
<AreaName>Virginia</AreaName>
<Median>39.92</Median>
<Pct10>22.69</Pct10>
<Pct25>29.83</Pct25>
<Pct75>49.45</Pct75>
<Pct90>61.5</Pct90>
<RateType>Hourly</RateType>
<StFips>51</StFips>
</WageDetails>
<WageDetails>
<Area>000051</Area>
<AreaName>Virginia</AreaName>
<Median>83040</Median>
<Pct10>47200</Pct10>
<Pct25>62050</Pct25>
<Pct75>102850</Pct75>
<Pct90>127920</Pct90>
<RateType>Annual</RateType>
<StFips>51</StFips>
</WageDetails>
</WageInfo>
</LocationWageDetails>
</LocationWageDetails>
<OccupationCode>171011</OccupationCode>
<OccupationName>Architects, Except Landscape and Naval</OccupationName>
<Request>
<InputOccupation>17-1011.00</InputOccupation>
<InputOccupationCode>17-1011.00</InputOccupationCode>
<InputOccupationTitle>Architects, Except Landscape and Naval</InputOccupationTitle>
</Request>
<SocInfo>
<SocCode>171011</SocCode>
<SocDescription>Plan and design structures, such as private residences, office buildings, theaters, factories, and other structural property. Excludes "Landscape Architects" and "Marine Engineers and Naval Architects".</SocDescription>
<SocTitle>Architects, Except Landscape and Naval</SocTitle>
</SocInfo>
</WagesByOccupations>
<WagesByOccupations>
<LocationWageDetails>
<LocationWageDetails>
<InputLocation>ca</InputLocation>
<LocationName>California</LocationName>
<WageInfo>
<WageDetails>
<Area>000006</Area>
<AreaName>California</AreaName>
<Median>61</Median>
<Pct10>45.65</Pct10>
<Pct25>53.63</Pct25>
<Pct75>74.89</Pct75>
<Pct90>91.87</Pct90>
<RateType>Hourly</RateType>
<StFips>06</StFips>
</WageDetails>
<WageDetails>
<Area>000006</Area>
<AreaName>California</AreaName>
<Median>126890</Median>
<Pct10>94940</Pct10>
<Pct25>111550</Pct25>
<Pct75>155780</Pct75>
<Pct90>191090</Pct90>
<RateType>Annual</RateType>
<StFips>06</StFips>
</WageDetails>
</WageInfo>
</LocationWageDetails>
<LocationWageDetails>
<InputLocation>va</InputLocation>
<LocationName>Virginia</LocationName>
<WageInfo>
<WageDetails>
<Area>000051</Area>
<AreaName>Virginia</AreaName>
<Median>49.27</Median>
<Pct10>36.7</Pct10>
<Pct25>42.42</Pct25>
<Pct75>58.11</Pct75>
<Pct90>64.63</Pct90>
<RateType>Hourly</RateType>
<StFips>51</StFips>
</WageDetails>
<WageDetails>
<Area>000051</Area>
<AreaName>Virginia</AreaName>
<Median>102480</Median>
<Pct10>76330</Pct10>
<Pct25>88220</Pct25>
<Pct75>120870</Pct75>
<Pct90>134430</Pct90>
<RateType>Annual</RateType>
<StFips>51</StFips>
</WageDetails>
</WageInfo>
</LocationWageDetails>
</LocationWageDetails>
<OccupationCode>291171</OccupationCode>
<OccupationName>Nurse Practitioners</OccupationName>
<Request>
<InputOccupation>29-1171.00</InputOccupation>
<InputOccupationCode>29-1171.00</InputOccupationCode>
<InputOccupationTitle>Nurse Practitioners</InputOccupationTitle>
</Request>
<SocInfo>
<SocCode>291171</SocCode>
<SocDescription>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.</SocDescription>
<SocTitle>Nurse Practitioners</SocTitle>
</SocInfo>
</WagesByOccupations>
</OccupationsList>
<RecordCount>2</RecordCount>
<sortBy>Hourly</sortBy>
<sortColumns>OT</sortColumns>
<sortOrder>ASC</sortOrder>
</CompareWagesByLocations>

Response Parameters

Name	Description	Type	Parent
ErrorMessage	Error message	String	Empty Cell
InValidOccupations	List of invalid occupations, among those in the request parameter	List of Strings	Empty Cell
InValidLocations	List of invalid locations, among those in the request paramenters	List of Strings	Empty Cell
RecordCount	Number of occupations in the request, even if two or more of the occupations corresponds to the same occupation for purposes of wage data.	Integer	Empty Cell
Keyword	The user input itself, for occupations to compare. Could be one or more occupations (O*NET or SOC title or code) separated by \| ("pipe" or "bar"). Example: 17-1011\|29-1171 \|Tellers	String	Empty Cell
Location	The user input itself, for locations to compare. Could be city and state (example: Chicago, IL), state (IL), or ZIP code (60050); or multiple locations separated by a \| ('pipe" or "bar"). Example: Chicago, IL \| FL \| 02134	String	Empty Cell
SortColumns	Column by which the data is sorted. Values include LT - Location title (default) LW - Low wage MW - Median wage HW - High wage	String	Empty Cell
SortOrder	Sort Direction. Values include: 0-ASC (default) ASC - Ascending DESC - Descending	String	Empty Cell
sortBy	sortBy Values include: 0 - Hourly (default) Hourly Annual	String	Empty Cell
OccupationsList	List of wage info for all the combinations of occupations and locations	List of Objects	Empty Cell
OccupationName	Occupation title	String	OccupationsList
OccupationCode	Occupation code	String	OccupationsList
Request	Request	Object	OccupationsList
InputOccupation	This occupation, as entered in API request (unedited)	String	Request
InputOccupationCode	This occupation code, well formatted	String	Request
InputOccupationTitle	This occupation title, official spelling and capitalization	String	Request
SocInfo	if Input occupation is an OES-specific occupation, the SocInfo identifies one of the corresponding SOC occupations.	Object	OccupationsList
SocCode	OES occupation code	String	SocInfo
SocTitle	OES occupation title	String	SocInfo
SocDescription	OES occupation description	String	SocInfo
LocationWageDetails	Wage details for this occupation, for this location	List of Objects	OccupationsList
LocationName	Location name, well formatted. If input location was a state, this parm is the name of that state. If it was a city or ZIP, this parm is the OES-defined region associated with that location, for which the API is now providing wage data. Some city names are associated with multiple OES-difined areas, due to the way we mesh USPS info with OES data.	String	LocationWageDetails
InputLocation	Input location	String	LocationWageDetails
WageInfo	Wage info for one location, one occupation, from BLS OEWS. Please note: When wage data is displayed, '115+' indicates the hourly wage is equal to or greater than $115.00, while '239,200' indicates an annual salary equal to or greater than $239,200.	List of Objects	LocationWageDetails
RateType	Rate Type can be Hourly or Annual. Some occupations have only hourly wages, or only annual.	String	WageInfo
Pct10	Wage at 10th percentile	String	WageInfo
Pct25	Wage at 25th percentile	String	WageInfo
Median	Wage at median	String	WageInfo
Pct75	Wage at 75th percentile	String	WageInfo
Pct90	Wage at 90th percentile	String	WageInfo
StFips	State FIPS code	String	WageInfo
Area	Code association with LocationName. Could be a state as a whole, or a metropolitan area (MSA or MNECTA), or a nonmetropolitan area defined by BLS OES.	String	WageInfo
AreaName	Redundant with LocationName	String	WageInfo
MetaData	Information about the source of the API	Object	Empty Cell
Publisher	Publisher of the API	String	MetaData
Sponsor	Sponsor of the API	String	MetaData
LastAccessDate	When the API was run, using Unix "epoch" format. Convert to date and time using a Unix epoch converter.	String	MetaData
CitationSuggested	If you use this data, CareerOneStop suggests you use this citation.	String	MetaData
DataSource	The data source object(s)	List of Objects	MetaData
DataName	Name of data	String	DataSource
DataSourceName	Name of data source	String	DataSource
DataSourceUrl	Url of data source	String	DataSource
DataLastUpdate	Date when CareerOneStop last updated this data	String	DataSource
DataVintageOrVersion	Version or vintage of the data	String	DataSource
DataDescription	Description of the data	String	DataSource
DataSourceCitation	Suggested citation for this data source	String	DataSource

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.

For help using the CareerOneStop website:
info@careeronestop.org