/taxonomies

Search taxonomies using either whole keywords (relevance search) or partial keywords (autocomplete), or list taxonomy items.

`GET` /taxonomies

Get a list of current available taxonomy facets.

Code Examples

curl --request GET \
  --url https://api.lightcast.io/jpa/taxonomies \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Response Examples

{
  "data": [
    "cip2",
    "cip4",
    "cip6",
    "city",
    "company",
    "county",
    "edulevels",
    "employment_type",
    "fips",
    "lightcast_sectors",
    "lot_career_area",
    "lot_occupation",
    "lot_occupation_group",
    "lot_specialized_occupation",
    "msa",
    "naics2",
    "naics3",
    "naics4",
    "naics5",
    "naics6",
    "onet",
    "remote_type",
    "skill_categories",
    "skill_subcategories",
    "skills",
    "soc2",
    "soc3",
    "soc4",
    "soc5",
    "state",
    "title"
  ]
}

`GET` /taxonomies/{facet}

Search taxonomies using either whole keywords (relevance search) or partial keywords (autocomplete).

URL Parameters

Name	Type	Description
`facet`	enum	Which taxonomy to search for ID/name suggestions. Example: `title` Must be one of: `benefit_categories`, `benefit`, `city`, `cip2`, `cip4`, `cip6`, `company`, `county`, `edulevels`, `employment_type`, `fips`, `laa_admin_area_1`, `laa_admin_area_2`, `laa_country`, `laa_metro`, `lot_career_area`, `lot_occupation_group`, `lot_occupation`, `lot_specialized_occupation`, `msa`, `naics2`, `naics3`, `naics4`, `naics5`, `naics6`, `onet`, `remote_type`, `skill_categories`, `skill_subcategories`, `skills`, `soc2`, `soc3`, `soc4`, `soc5`, `state`, `title`

Query Parameters

Name	Type	Description
`q`	string	A query string of whole or partial keywords to search for. Only when `autocomplete` is true is `q` is assumed to be a prefix. If `q` is omitted, the response will list results sorted by id of length `limit`. This parameter is optional. Example: data sci
`autocomplete`	boolean	Autocomplete search terms. Only used in combination with `q`. `true` - Performs fast prefix-enabled search using only primary and, if available, alternate names (alternate names currently available for ONET and skills). `false` - Performs more extensive search using both name(s) and, if available, description (description currently only available for SOC and ONET search). This parameter is optional. Default: `true`
`limit`	integer	How many search results to return. This parameter is optional. Minimum: `1` Maximum: `10000` Default: `10`
`area_version`	enum	Specify US Area taxonomy version to use. This parameter is optional. Default: `us_area_2024_4` Must be one of: `us_area_2024_3`, `us_area_2024_4`
`soc_version`	enum	Specify SOC taxonomy version to use. This parameter is optional. Default: `soc_2021` Must be one of: `soc_2021`
`onet_version`	enum	Specify ONET taxonomy version to use. This parameter is optional. Default: `onet_2019` Must be one of: `onet_2019`
`title_version`	enum	Specify Job Title taxonomy version to use. This parameter is optional. Default: `emsi` Must be one of: `emsi`
`company_version`	enum	Specify company taxonomy version to use. This parameter is optional. Default: `emsi_company` Must be one of: `emsi_company`
`naics_version`	enum	Specify NAICS taxonomy version to use. This parameter is optional. Default: `naics_std_2022` Must be one of: `naics_std_2022`
`new_taxonomy_versions`	enum	Use new taxonomy versions. This parameter is optional. Must be one of: `true`, `false`
`area_us_version`	enum	Specify US Area taxonomy version to use. This parameter is optional. Default: `2.0.0` Must be one of: `1.0.2`, `2.0.0`
`soc_lightcast_version`	enum	Specify SOC Lightcast taxonomy version to use. This parameter is optional. Default: `2018.2021.0` Must be one of: `2018.2021.0`
`onet_standard_version`	enum	Specify ONET Standard taxonomy version to use. This parameter is optional. Default: `2019.0.0` Must be one of: `2019.0.0`
`lot_version`	enum	Specify LOT taxonomy version to use. This parameter is optional. Default: `7` Must be one of: `6`, `7`

Code Examples

curl --request GET \
  --url 'https://api.lightcast.io/jpa/taxonomies/title?q=data%20sci' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Response Examples

{
  "data": [
    {
      "id": "ET3B93055220D592C8",
      "name": "Data Scientists",
      "properties": {
        "singular_name": "Data Scientist",
        "unique_postings": 2293
      },
      "score": 8.407919
    },
    {
      "id": "ETFCE878A7B95881A6",
      "name": "Data Specialists",
      "properties": {
        "singular_name": "Data Specialist",
        "unique_postings": 1683
      },
      "score": 5.7275753
    },
    {
      "id": "ET4FFD0730E6B6C21A",
      "name": "Database Specialists",
      "properties": {
        "singular_name": "Database Specialist",
        "unique_postings": 927
      },
      "score": 5.7275753
    },
    {
      "id": "ET85FAA8C1FD151D5C",
      "name": "Minimum Data Set (MDS) Nurses",
      "properties": {
        "singular_name": "Minimum Data Set (MDS) Nurse",
        "unique_postings": 821
      },
      "score": 4.0093026
    },
    {
      "id": "ETECC216EB6E8D41E0",
      "name": "Minimum Data Set (MDS) Coordinators",
      "properties": {
        "singular_name": "Minimum Data Set (MDS) Coordinator",
        "unique_postings": 764
      },
      "score": 4.0093026
    }
  ]
}

//Your request wasn't valid (bad parameter names or values).

{
  "errors": [
    {
      "status": 400,
      "title": "Malformed Request",
      "detail": "Expected array"
    }
  ]
}

//The facet you requested wasn't found.

{
  "errors": [
    {
      "status": 404,
      "title": "URL not found",
      "detail": "Unrecognized facet 'foo'"
    }
  ]
}

`POST` /taxonomies/{facet}/lookup

Look up taxonomy items by ID.

URL Parameters

Name	Type	Description
`facet`	enum	Which taxonomy to look up IDs in. Example: `title` Must be one of: `cip2`, `cip4`, `cip6`, `city`, `company`, `county`, `edulevels`, `employment_type`, `fips`, `laa_admin_area_1`, `laa_admin_area_2`, `laa_country`, `laa_metro`, `lot_career_area`, `lot_occupation`, `lot_occupation_group`, `lot_specialized_occupation`, `msa`, `naics2`, `naics3`, `naics4`, `naics5`, `naics6`, `onet`, `remote_type`, `skills`, `soc2`, `soc3`, `soc4`, `soc5`, `state`, `title`

Query Parameters

Name	Type	Description
`area_version`	enum	Specify US Area taxonomy version to use. This parameter is optional. Default: `us_area_2024_4` Must be one of: `us_area_2024_3`, `us_area_2024_4`
`soc_version`	enum	Specify SOC taxonomy version to use. This parameter is optional. Default: `soc_2021` Must be one of: `soc_2021`
`onet_version`	enum	Specify ONET taxonomy version to use. This parameter is optional. Default: `onet_2019` Must be one of: `onet_2019`
`title_version`	enum	Specify Job Title taxonomy version to use. This parameter is optional. Default: `emsi` Must be one of: `emsi`
`company_version`	enum	Specify company taxonomy version to use. This parameter is optional. Default: `emsi_company` Must be one of: `emsi_company`
`naics_version`	enum	Specify NAICS taxonomy version to use. This parameter is optional. Default: `naics_std_2022` Must be one of: `naics_std_2022`
`new_taxonomy_versions`	enum	Use new taxonomy versions. This parameter is optional. Must be one of: `true`, `false`
`area_us_version`	enum	Specify US Area taxonomy version to use. This parameter is optional. Default: `2.0.0` Must be one of: `1.0.2`, `2.0.0`
`soc_lightcast_version`	enum	Specify SOC Lightcast taxonomy version to use. This parameter is optional. Default: `2018.2021.0` Must be one of: `2018.2021.0`
`onet_standard_version`	enum	Specify ONET Standard taxonomy version to use. This parameter is optional. Default: `2019.0.0` Must be one of: `2019.0.0`
`lot_version`	enum	Specify LOT taxonomy version to use. This parameter is optional. Default: `7` Must be one of: `6`, `7`

Request Body

{
  "ids": [
    "ETEB3BB8E555C79368"
  ]
}

Code Examples

curl --request POST \
  --url https://api.lightcast.io/jpa/taxonomies/title/lookup \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": [ "ETEB3BB8E555C79368" ] }'

Response Examples

{
  "data": [
    {
      "id": "ET3B93055220D592C8",
      "name": "Data Scientists",
      "properties": {
        "singular_name": "Data Scientist",
        "unique_postings": 2293
      }
    }
  ]
}

//Your request wasn't valid (bad parameter names or values).

{
  "errors": [
    {
      "status": 400,
      "title": "Malformed Request",
      "detail": "Expected array"
    }
  ]
}

//The facet you requested wasn't found.

{
  "errors": [
    {
      "status": 404,
      "title": "URL not found",
      "detail": "Unrecognized facet 'foo'"
    }
  ]
}

/taxonomies

GET /taxonomies

Code Examples

Response Examples

GET /taxonomies/{facet}

URL Parameters

Query Parameters

Code Examples

Response Examples

POST /taxonomies/{facet}/lookup

URL Parameters

Query Parameters

Request Body

Code Examples

Response Examples

`GET` /taxonomies

`GET` /taxonomies/{facet}

`POST` /taxonomies/{facet}/lookup