Endpoint Examples

/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/profiles/taxonomies \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Response Examples

{
  "data": [
    "cip2",
    "cip4",
    "cip6",
    "city",
    "company",
    "county",
    "edulevels",
    "fips",
    "msa",
    "naics2",
    "naics3",
    "naics4",
    "naics5",
    "naics6",
    "onet",
    "schools",
    "schools_ipeds",
    "skills",
    "soc2",
    "soc3",
    "soc4",
    "soc5",
    "state",
    "title",
    "gender"
  ]
}

`GET` /taxonomies/{facet}

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

Path Parameters

Name Type Description

Name	Type	Description
`facet`	enum	Which taxonomy to search for ID/name suggestions. (Cities will always have a null ID.) Example: title Must be one of: `cip2`, `cip4`, `cip6`, `city`, `company`, `county`, `edulevels`, `fips`, `msa`, `naics2`, `naics3`, `naics4`, `naics5`, `naics6`, `onet`, `schools`, `skill_categories`, `skill_subcategories`, `skills`, `soc2`, `soc3`, `soc4`, `soc5`, `state`, `title`

facet

enum

Which taxonomy to search for ID/name suggestions. (Cities will always have a null ID.)

Example: title
Must be one of: cip2, cip4, cip6, city, company, county, edulevels, fips, msa, naics2, naics3, naics4, naics5, naics6, onet, schools, skill_categories, skill_subcategories, skills, soc2, soc3, soc4, soc5, state, title

Query Parameters

Name	Type	Decription
`q`	string	A query string of whole or partial keywords to search for. Only when `autocomplete` is true is `q` assumed to be a prefix. This parameter is optional. Example: `data sci`
`autocomplete`	boolean	Autocomplete search terms. 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`
`title_version`	enum	Specify Job Title taxonomy version to use. This parameter is optional. Default: `emsi` Must be one of: `emsi`
`cip_version`	enum	Specify CIP taxonomy version to use. This parameter is optional. Default: `cip2010` Must be one of: `cip2010`, `cip2020`
`company_version`	enum	Specify company taxonomy version to use. This parameter is optional. Default: `emsi_company` Must be one of: `emsi_company`
`onet_version`	enum	Specify ONET taxonomy version to use. This parameter is optional. Default: `onet_2019` Must be one of: `onet_2019`
`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: `1.0.3` Must be one of: `1.0.2`, `1.0.3`
`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: `7`, `6`

Code Examples

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

Response Examples

{
  "data": [
    {
      "id": "ET3B93055220D592C8",
      "name": "Data Scientists",
      "properties": {
        "profiles": 74205,
        "singular_name": "Data Scientist"
      },
      "score": 115.72626
    },
    {
      "id": "ET66EFA7BC3A32BB32",
      "name": "Managers/Data Scientists",
      "properties": {
        "profiles": 20745,
        "singular_name": "Manager/Data Scientist"
      },
      "score": 102.61432
    },
    {
      "id": "ET3B7D691B9A3FCB65",
      "name": "Data Science Interns",
      "properties": {
        "profiles": 18368,
        "singular_name": "Data Science Intern"
      },
      "score": 98.123924
    },
    {
      "id": "ET6F4C400F82935C3E",
      "name": "Data Science Managers",
      "properties": {
        "profiles": 7863,
        "singular_name": "Data Science Manager"
      },
      "score": 93.68677
    },
    {
      "id": "ETB15B6675998124CE",
      "name": "Lead Data Scientists",
      "properties": {
        "profiles": 6377,
        "singular_name": "Lead Data Scientist"
      },
      "score": 88.615845
    },
    {
      "id": "ET8428FBC2C9F2D438",
      "name": "Directors of Data Science",
      "properties": {
        "profiles": 7306,
        "singular_name": "Director of Data Science"
      },
      "score": 87.80374
    },
    {
      "id": "ETC81FBF8B48383129",
      "name": "Clinical Data Scientists",
      "properties": {
        "profiles": 3957,
        "singular_name": "Clinical Data Scientist"
      },
      "score": 87.298096
    },
    {
      "id": "ETE22C6070B93851E0",
      "name": "Data Science Fellows",
      "properties": {
        "profiles": 5384,
        "singular_name": "Data Science Fellow"
      },
      "score": 87.09463
    },
    {
      "id": "ET486D61EA8B4CBC36",
      "name": "Data Science Consultants",
      "properties": {
        "profiles": 3569,
        "singular_name": "Data Science Consultant"
      },
      "score": 84.95645
    },
    {
      "id": "ET64F3ADF2602703BD",
      "name": "Data Science and Analytics Managers",
      "properties": {
        "profiles": 6138,
        "singular_name": "Data Science and Analytics Manager"
      },
      "score": 84.30433
    }
  ]
}

//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

Lookup taxonomy items by ID.

Path Parameters

Name Type Description

Name	Type	Description
`facet`	enum	Which taxonomy to to look up IDs in. Example: title Must be one of: `cip2`, `cip4`, `cip6`, `city`, `company`, `county`, `edulevels`, `fips`, `msa`, `naics2`, `naics3`, `naics4`, `naics5`, `naics6`, `onet`, `schools`, `schools_ipeds`, `skills`, `soc2`, `soc3`, `soc4`, `soc5`, `state`, `title`

facet

enum

Which taxonomy to to look up IDs in.

Example: title

Must be one of: cip2, cip4, cip6, city, company, county, edulevels, fips, msa, naics2, naics3, naics4, naics5, naics6, onet, schools, schools_ipeds, 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`
`title_version`	enum	Specify Job Title taxonomy version to use. This parameter is optional. Default: `emsi` Must be one of: `emsi`
`cip_version`	enum	Specify CIP taxonomy version to use. This parameter is optional. Default: `cip2010` Must be one of: `cip2010`, `cip2020`
`company_version`	enum	Specify company taxonomy version to use. This parameter is optional. Default: `emsi_company` Must be one of: `emsi_company`
`onet_version`	enum	Specify ONET taxonomy version to use. This parameter is optional. Default: `onet_2019` Must be one of: `onet_2019`
`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: `1.0.3` Must be one of: `1.0.2`, `1.0.3`
`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: `7`, `6`

Request Body

{
  "ids": [
    "ETEB3BB8E555C79368"
  ]
}

Code Examples

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

Response Examples

{
  "data": [
    {
      "id": "ETEB3BB8E555C79368",
      "name": ".NET Developers",
      "properties": {
        "profiles": 37469,
        "singular_name": ".NET Developer"
      }
    }
  ]
}

//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}

Path Parameters

Query Parameters

Code Examples

Response Examples

POST /taxonomies/{facet}/lookup

Path Parameters

Query Parameters

Request Body

Code Examples

Response Examples

`GET` /taxonomies

`GET` /taxonomies/{facet}

`POST` /taxonomies/{facet}/lookup