Banner: Web API: Validate Location and Get Areas

Web API: Validate Location and Get Areas

Validate Location and Get Areas

'Validate Location and Get Areas' enables developers to validate location input, and to retrieve identities of geographical areas with which it is associated: the state or territory; all the counties and county-equivalents; and all “areas” including Metropolitan Statistical Areas, Metropolitan NECTA areas, and OES-defined nonmetropolitan areas.

About this data

Location cross-walk information was assembled by COS staff using data from the following sources: (1) U.S. Census Bureau (2) U.S. Department of Labor, Bureau of Labor Statistics, Occupational Employment and Wage Statistics (OEWS) program (3) www.unitedstateszipcodes.org

Resource URL

https://api.careeronestop.org/v1/location/{userId}/{location}

Try this Web API

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/location/{userId}/{location}",

                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/location/{userId}/{location}")               

        .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
location String Required This value accepts a city, state (Reston, VA), state (VA) or ZIP code (20191) or US for national data
enableMetaData boolean Required Use this parameter to include response MetaData

Response Structure

{
  "State": "Virginia",
  "StateAbbreviation": "VA",
  "STFIPS": "51",
  "Type": "ZipCode",
  "PrimaryArea": "",
  "InputLocation": "20171",
  "Counties": [
    {
      "AreaType": "County",
      "Area": "000059",
      "AreaName": "Fairfax County",
      "CountyFIPS": "51059"
    }
  ],
  "MetroAndNonmetroAreas": [
    {
      "AreaType": "MSA",
      "Area": "047900",
      "AreaName": "Washington-Arlington-Alexandria, DC-VA-MD-WV Metro Area",
      "CountyFIPS": ""
    }
  ],
  "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": 1566934229,
    "CitationSuggested": "This data is delivered by an API from CareerOneStop, sponsored by U.S. Department of Labor, Employment and Training Administration.  www.careeronestop.org\nLocation cross-walk information was assembled by COS staff using data from the following sources:\n(1) U.S. Census Bureau \n(2) U.S. Department of Labor, Bureau of Labor Statistics, Occupational Employment Statistics (OES) program\n(3) www.unitedstateszipcodes.org",
    "DataSource": [
      {
        "DataName": "Census Delineation Files, \"List1\"",
        "DataSourceName": "U.S. Census Bureau",
        "DataSourceUrl": "https://www.census.gov/geographies/reference-files/time-series/demo/metro-micro/delineation-files.html",
        "DataLastUpdate": "5/1/15",
        "DataVintageOrVersion": "5/1/15",
        "DataDescription": "All Metropolitan Statistical Areas in all states plus DC and PR; all counties and county equivalents"
        "DataSourceCitation": "Data from U.S. Census Bureau, Census Delineation Files, List1, last updated 5/1/2015, https://www.census.gov/geographies/reference-files/time-series/demo/metro-micro/delineation-files.html"
      },
      {
        "DataName": "Wages by occupation",
        "DataSourceName": "U.S. Department of Labor, Bureau of Labor Statistics, Occupational Employment Statistics program",
        "DataSourceUrl": "https://www.bls.gov/oes/",
        "DataLastUpdate": "7/1/19",
        "DataVintageOrVersion": "May-18",
        "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.\nOES uses metropolitan areas (MSA's and MNECTA's) that are defined by OMB; and also \"\"balance of state\"\" areas that are defined and used only by OES. COS uses these definitions in our algorithm."
        "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/)."
      },
      {
        "DataName": "United States Zip Codes",
        "DataSourceName": "United States Zip Codes",
        "DataSourceUrl": "https://www.unitedstateszipcodes.org",
        "DataLastUpdate": "3/1/19",
        "DataVintageOrVersion": "3/1/19",
        "DataDescription": "Zip codes, cities, counties"
        "DataSourceCitation": "Zip code data is from United States Zip Codes (https://www.unitedstateszipcodes.org), downloaded 3/1/2019."
      }
    ]
  }
}

<Location
xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://schemas.datacontract.org/2004/07/XPAND.CareerOneStop.WebApi.ViewModels">
  <Counties>
    <AreaInfo>
      <Area>000059</Area>
      <AreaName>Fairfax County</AreaName>
      <AreaType>County</AreaType>
      <CountyFIPS>51059</CountyFIPS>
    </AreaInfo>
  </Counties>
  <InputLocation>20171</InputLocation>
  <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
      Location cross-walk information was assembled by COS staff using data from the following sources:
      (1) U.S. Census Bureau
      (2) U.S. Department of Labor, Bureau of Labor Statistics, Occupational Employment Statistics (OES) program
      (3) www.unitedstateszipcodes.org
    </d2p1:CitationSuggested>
    <d2p1:DataSource>
      <d2p1:MetaDataSource>
        <d2p1:DataDescription>All Metropolitan Statistical Areas in all states plus DC and PR; all counties and county equivalents</d2p1:DataDescription>
        <d2p1:DataLastUpdate>5/1/15</d2p1:DataLastUpdate>
        <d2p1:DataName>Census Delineation Files, "List1"</d2p1:DataName>
        <d2p1:DataSourceCitation>Data from U.S. Census Bureau, Census Delineation Files, List1, last updated 5/1/2015, https://www.census.gov/geographies/reference-files/time-series/demo/metro-micro/delineation-files.html</d2p1:DataSourceCitation>
        <d2p1:DataSourceName>U.S. Census Bureau</d2p1:DataSourceName>
        <d2p1:DataSourceUrl>https://www.census.gov/geographies/reference-files/time-series/demo/metro-micro/delineation-files.html</d2p1:DataSourceUrl>
        <d2p1:DataVintageOrVersion>5/1/15</d2p1:DataVintageOrVersion>
      </d2p1:MetaDataSource>
      <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.
          OES uses metropolitan areas (MSA's and MNECTA's) that are defined by OMB; and also ""balance of state"" areas that are defined and used only by OES. COS uses these definitions in our algorithm.
        </d2p1:DataDescription>
        <d2p1:DataLastUpdate>7/1/19</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, Occupational Employment Statistics program</d2p1:DataSourceName>
        <d2p1:DataSourceUrl>https://www.bls.gov/oes/</d2p1:DataSourceUrl>
        <d2p1:DataVintageOrVersion>May-18</d2p1:DataVintageOrVersion>
      </d2p1:MetaDataSource>
      <d2p1:MetaDataSource>
        <d2p1:DataDescription>Zip codes, cities, counties</d2p1:DataDescription>
        <d2p1:DataLastUpdate>3/1/19</d2p1:DataLastUpdate>
        <d2p1:DataName>United States Zip Codes</d2p1:DataName>
        <d2p1:DataSourceCitation>Zip code data is from United States Zip Codes (https://www.unitedstateszipcodes.org), downloaded 3/1/2019.</d2p1:DataSourceCitation>
        <d2p1:DataSourceName>United States Zip Codes</d2p1:DataSourceName>
        <d2p1:DataSourceUrl>https://www.unitedstateszipcodes.org</d2p1:DataSourceUrl>
        <d2p1:DataVintageOrVersion>3/1/19</d2p1:DataVintageOrVersion>
      </d2p1:MetaDataSource>
    </d2p1:DataSource>
    <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>
  <MetroAndNonmetroAreas>
    <AreaInfo>
      <Area>047900</Area>
      <AreaName>Washington-Arlington-Alexandria, DC-VA-MD-WV Metro Area</AreaName>
      <AreaType>MSA</AreaType>
      <CountyFIPS i:nil="true"/>
    </AreaInfo>
  </MetroAndNonmetroAreas>  <PrimaryArea i:nil="true"/>  <STFIPS>51</STFIPS>
  <State>Virginia</State>
  <StateAbbreviation>VA</StateAbbreviation>
  <Type>ZipCode</Type>
</Location>

Response Parameters

Name
Description
Type
Parent
State
State Name
String
Empty Cell
StateAbbreviation
State abbreviation
String
Empty Cell
STFIPS
State FIPS
String
Empty Cell
Type
Location type
String
Empty Cell
PrimaryArea
Primary Area
String
Empty Cell
InputLocation
The request parameter
String
Empty Cell
Counties
The whole list of counties
Object
Empty Cell
AreaType
Area type information
String
Counties
Area
Area code
String
Counties
AreaName
Area name
String
Counties
CountyFIPS
County FIPS information
String
Counties
MetroAndNonmetroAreas
The list of area informations
Object
Empty Cell
AreaType
The type of area
String
MetroAndNonmetroAreas
Area
Area code
String
MetroAndNonmetroAreas
AreaName
Area name
String
MetroAndNonmetroAreas
CountyFIPS
County FIPS information
String
MetroAndNonmetroAreas
MetaData
MetaData information
Object
Empty Cell
Publisher
Publisher of the API
String
MetaData
Sponsor
Sponsor of the API
String
MetaData
LastAccessDate
Date for last access
String
MetaData
CitationSuggested
If you use this API, CareerOneStop suggests you use this citation.
String
MetaData
DataSource
The data source object
Object
MetaData
DataName
Name of data
String
DataSource
DataSourceName
Name of data source
String
DataSource
DataSourceUrl
Url of data source
String
DataSource
DataLastUpdate
Data Last updated time
String
DataSource
DataVintageOrVersion
Version of data
String
DataSource
DataDescription
Description of 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.