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

Response Examples

{
  "data": [
    "cd",
    "city",
    "cma",
    "company",
    "contract_type",
    "csd",
    "edulevels",
    "employment_type",
    "laa_admin_area_1",
    "laa_admin_area_2",
    "laa_country",
    "laa_metro",
    "language",
    "lot_career_area",
    "lot_occupation",
    "lot_occupation_group",
    "lot_specialized_occupation",
    "naics2",
    "naics3",
    "naics4",
    "naics5",
    "naics6",
    "noc1",
    "noc2",
    "noc3",
    "noc4",
    "noc5",
    "pr",
    "province",
    "remote_type",
    "skill_categories",
    "skill_subcategories",
    "skills",
    "title"
  ]
}

`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: `cd`, `city`, `cma`, `company`, `csd`, `edulevels`, `employment_type`, `laa_admin_area_1`, `laa_admin_area_2`, `laa_country`, `laa_metro`, `lot_career_area`, `lot_occupation_group`, `lot_occupation`, `lot_specialized_occupation`, `lot_career_area_name`, `lot_occupation_group_name`, `lot_occupation_name`, `lot_specialized_occupation_name`, `naics2`, `naics3`, `naics4`, `naics5`, `naics6`, `noc1`, `noc2`, `noc3`, `noc4`, `noc5`, `pr`, `province`, `remote_type`, `skill_categories`, `skill_subcategories`, `skills`, `title`

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: cd, city, cma, company, csd, edulevels, employment_type, laa_admin_area_1, laa_admin_area_2, laa_country, laa_metro, lot_career_area, lot_occupation_group, lot_occupation, lot_specialized_occupation, lot_career_area_name, lot_occupation_group_name, lot_occupation_name, lot_specialized_occupation_name, naics2, naics3, naics4, naics5, naics6, noc1, noc2, noc3, noc4, noc5, pr, province, remote_type, skill_categories, skill_subcategories, skills, 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 skills). `false` - Performs more extensive search using both name(s) and, if available, description (description currently only available for NOC 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`
`noc_version`	enum	Specify NOC taxonomy version to use. This parameter is optional. Default: `ca_noc2021` Must be one of: `ca_noc2021`
`company_version`	enum	Specify company taxonomy version to use. This parameter is optional. Default: `emsi_company` Must be one of: `emsi_company`
`area_version`	enum	Specify area taxonomy version to use. This parameter is optional. Default: `ca_area_sgc2016` Must be one of: `ca_area_sgc2016`, `ca_area_sgc2021`
`area_ca_version`	enum	Specify area taxonomy version to use. This parameter is optional. Default: `2021.0.0` Must be one of: `2021.0.0`, `2016.0.0`
`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`
`naics_version`	enum	Specify NAICS taxonomy version to use. This parameter is optional. Default: `naics_std_2017` Must be one of: `naics_std_2017`, `naics_std_2022`
`naics_standard_version`	enum	Specify NAICS taxonomy version to use. This parameter is optional. Default: `2017.0.1` Must be one of: `2017.0.1`, `2022.0.0`

Code Examples

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

Response Examples

{
  "data": [
    {
      "id": "ET3301B62626426FD5",
      "name": "Data Science Engineers",
      "properties": {
        "singular_name": "Data Science Engineer",
        "unique_postings": 7271
      },
      "score": 129.431
    },
    {
      "id": "ET3B7D691B9A3FCB65",
      "name": "Data Science Interns",
      "properties": {
        "singular_name": "Data Science Intern",
        "unique_postings": 7271
      },
      "score": 129.431
    },
    {
      "id": "ET4609DFF814811067",
      "name": "Data Science Instructors",
      "properties": {
        "singular_name": "Data Science Instructor",
        "unique_postings": 7271
      },
      "score": 129.431
    },
    {
      "id": "ET486D61EA8B4CBC36",
      "name": "Data Science Consultants",
      "properties": {
        "singular_name": "Data Science Consultant",
        "unique_postings": 7271
      },
      "score": 129.431
    },
    {
      "id": "ET6B57FB37DA4AA8A8",
      "name": "Data Science Analysts",
      "properties": {
        "singular_name": "Data Science Analyst",
        "unique_postings": 7271
      },
      "score": 129.431
    },
    {
      "id": "ETB6084083D2283817",
      "name": "Data Science Associates",
      "properties": {
        "singular_name": "Data Science Associate",
        "unique_postings": 7271
      },
      "score": 129.431
    }
  ]
}

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

Name	Type	Description
`facet`	enum	Which taxonomy to look up IDs in. Example: `title` Must be one of: `cd`, `city`, `cma`, `company`, `csd`, `edulevels`, `employment_type`, `laa_admin_area_1`, `laa_admin_area_2`, `laa_country`, `laa_metro`, `lot_career_area`, `lot_occupation_group`, `lot_occupation`, `lot_specialized_occupation`, `lot_career_area_name`, `lot_occupation_group_name`, `lot_occupation_name`, `lot_specialized_occupation_name`, `naics2`, `naics3`, `naics4`, `naics5`, `naics6`, `noc1`, `noc2`, `noc3`, `noc4`, `noc5`, `pr`, `province`, `remote_type`, `skill_categories`, `skill_subcategories`, `skills`, `title`

facet

enum

Which taxonomy to look up IDs in.
Example: title

Must be one of: cd, city, cma, company, csd, edulevels, employment_type, laa_admin_area_1, laa_admin_area_2, laa_country, laa_metro, lot_career_area, lot_occupation_group, lot_occupation, lot_specialized_occupation, lot_career_area_name, lot_occupation_group_name, lot_occupation_name, lot_specialized_occupation_name, naics2, naics3, naics4, naics5, naics6, noc1, noc2, noc3, noc4, noc5, pr, province, remote_type, skill_categories, skill_subcategories, skills, title

Query Parameters

Name	Type	Description
`noc_version`	enum	Specify NOC taxonomy version to use. This parameter is optional. Default: `ca_noc2021` Must be one of: `ca_noc2021`
`company_version`	enum	Specify company taxonomy version to use. This parameter is optional. Default: `emsi_company` Must be one of: `emsi_company`
`area_version`	enum	Specify area taxonomy version to use. This parameter is optional. Default: `ca_area_sgc2016` Must be one of: `ca_area_sgc2016`, `ca_area_sgc2021`
`area_ca_version`	enum	Specify area taxonomy version to use. This parameter is optional. Default: `2021.0.0` Must be one of: `2021.0.0`, `2016.0.0`
`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`
`naics_version`	enum	Specify NAICS taxonomy version to use. This parameter is optional. Default: `naics_std_2017` Must be one of: `naics_std_2017`, `naics_std_2022`
`naics_standard_version`	enum	Specify NAICS taxonomy version to use. This parameter is optional. Default: `2017.0.11` Must be one of: `2017.0.1`, `2022.0.0`

Request Body

{
  "ids": [
    "ETEB3BB8E555C79368"
  ]
}

Code Examples

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

Response Examples

{
  "data": [
    {
      "id": "ET3301B62626426FD5",
      "name": "Data Science Engineers",
      "properties": {
        "singular_name": "Data Science Engineer"
      }
    }
  ]
}

//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'"
    }
  ]
}