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

Response Examples

{
  "data": [
    "city",
    "company",
    "country",
    "edulevels",
    "employment_type",
    "laa_admin_area_1",
    "laa_admin_area_2",
    "laa_country",
    "laa_metro",
    "lau1",
    "lot_career_area",
    "lot_occupation",
    "lot_occupation_group",
    "lot_specialized_occupation",
    "nuts1",
    "nuts3",
    "remote_type",
    "skill_categories",
    "skill_subcategories",
    "skills",
    "soc1",
    "soc2",
    "soc3",
    "soc4",
    "title",
    "ttwa",
    "uk_sic_1",
    "uk_sic_2",
    "uk_sic_3",
    "uk_sic_4",
    "uk_sic_5"
  ]
}

`GET` /taxonomies/{facet}

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

URL Parameters

Name Type Description

Name	Type	Description
`facet`	enum	Which taxonomy to search for ID/name suggestions (Cities will always have a null ID, and cannot be listed without a `q` query parameter). Example: `title` Must be one of:`city`, `company`, `country`, `edulevels`, `employment_type`, `laa_admin_area_1`, `laa_admin_area_2`, `laa_country`, `laa_metro`, `lau1`, `lot_career_area`, `lot_occupation_group`, `lot_occupation`, `lot_specialized_occupation`, `nuts1`, `nuts3`, `remote_type`, `skill_categories`, `skill_subcategories`, `skills`, `soc1`, `soc2`, `soc3`, `soc4`, `title`, `ttwa`, `uk_sic_1`, `uk_sic_2`, `uk_sic_3`, `uk_sic_4`, `uk_sic_5`

facet

enum

Which taxonomy to search for ID/name suggestions (Cities will always have a null ID, and cannot be listed without a q query parameter).
Example: title

Must be one of:city, company, country, edulevels, employment_type, laa_admin_area_1, laa_admin_area_2, laa_country, laa_metro, lau1, lot_career_area, lot_occupation_group, lot_occupation, lot_specialized_occupation, nuts1, nuts3, remote_type, skill_categories, skill_subcategories, skills, soc1, soc2, soc3, soc4, title, ttwa, uk_sic_1, uk_sic_2, uk_sic_3, uk_sic_4, uk_sic_5

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 skills). `false` - Performs more extensive search using name(s). This parameter is optional. Default: `true`
`limit`	integer	How many search results to return. This parameter is optional. Minimum: `1` Maximum: `10000` Default: `10`
`soc_version`	enum	Specify SOC taxonomy version to use. This parameter is optional. Default: `uk_soc_2020` Must be one of: `uk_soc_2020`
`area_version`	enum	Specify area taxonomy version to use. This parameter is optional. Default: `uk_area_2015` Must be one of: `uk_area_2015`
`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`
`new_taxonomy_versions`	enum	Use new taxonomy versions. This parameter is optional. Must be one of: `true`, `false`
`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/uk-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

Lookup taxonomy items by ID.

URL Parameters

Name Type Description

Name	Type	Description
`facet`	enum	Which taxonomy to to look up IDs in. Example: `title` Must be one of: `city`, `company`, `country`, `edulevels`, `employment_type`, `laa_admin_area_1`, `laa_admin_area_2`, `laa_country`, `laa_metro`, `lau1`, `lot_career_area`, `lot_occupation_group`, `lot_occupation`, `lot_specialized_occupation`, `nuts1`, `nuts3`, `remote_type`, `skill_categories`, `skill_subcategories`, `skills`, `soc1`, `soc2`, `soc3`, `soc4`, `title`, `ttwa`, `uk_sic_1`, `uk_sic_2`, `uk_sic_3`, `uk_sic_4`, `uk_sic_5`

facet

enum

Which taxonomy to to look up IDs in.
Example: title

Must be one of: city, company, country, edulevels, employment_type, laa_admin_area_1, laa_admin_area_2, laa_country, laa_metro, lau1, lot_career_area, lot_occupation_group, lot_occupation, lot_specialized_occupation, nuts1, nuts3, remote_type, skill_categories, skill_subcategories, skills, soc1, soc2, soc3, soc4, title, ttwa, uk_sic_1, uk_sic_2, uk_sic_3, uk_sic_4, uk_sic_5

Query Parameters

Name	Type	Description
`soc_version`	enum	Specify SOC taxonomy version to use. This parameter is optional. Default: `uk_soc_2020` Must be one of: `uk_soc_2020`
`area_version`	enum	Specify area taxonomy version to use. This parameter is optional. Default: `uk_area_2015` Must be one of: `uk_area_2015`
`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`
`new_taxonomy_versions`	enum	Use new taxonomy versions. This parameter is optional. Must be one of: `true`, `false`
`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/uk-jpa/taxonomies/title/lookup \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": [ "ETEB3BB8E555C79368" ] }'

Response Examples

{
  "data": [
    {
      "id": "ETEB3BB8E555C79368",
      "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