/rankings

Group and rank profiles by available facets.

`GET` /rankings

Get a list of current available ranking facets.

Code Examples

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

Response Examples

{
  "data": [
    "certifications",
    "certifications_name",
    "cip2",
    "cip2_name",
    "cip4",
    "cip4_name",
    "cip6",
    "cip6_name",
    "city",
    "city_name",
    "common_skills",
    "common_skills_name",
    "company",
    "company_name",
    "county",
    "county_name",
    "edulevels",
    "edulevels_name",
    "estimated_wage_p25",
    "estimated_wage_p50",
    "estimated_wage_p75",
    "fips",
    "fips_name",
    "gender",
    "gender_name",
    "grad_year",
    "is_fortune100",
    "is_fortune1000",
    "is_fortune500",
    "laa_country",
    "laa_country_name",
    "laa_metro",
    "laa_metro_name",
    "laa_admin_area_1",
    "laa_admin_area_1_name",
    "laa_admin_area_2",
    "laa_admin_area_2_name",
    "lot_career_area",
    "lot_career_area_name",
    "lot_occupation",
    "lot_occupation_group",
    "lot_occupation_group_name",
    "lot_occupation_name",
    "lot_specialized_occupation",
    "lot_specialized_occupation_name",
    "max_edulevels",
    "max_edulevels_name",
    "msa",
    "msa_name",
    "naics2",
    "naics2_name",
    "naics3",
    "naics3_name",
    "naics4",
    "naics4_name",
    "naics5",
    "naics5_name",
    "naics6",
    "naics6_name",
    "onet",
    "onet_name",
    "schools",
    "schools_ipeds",
    "schools_name",
    "skill_categories",
    "skill_categories_name",
    "skill_subcategories",
    "skill_subcategories_name",
    "skills",
    "skills_name",
    "soc2",
    "soc2_name",
    "soc3",
    "soc3_name",
    "soc4",
    "soc4_name",
    "soc5",
    "soc5_name",
    "software_skills",
    "software_skills_name",
    "specialized_skills",
    "specialized_skills_name",
    "state",
    "state_name",
    "title",
    "title_name"
  ]
}

`POST` /rankings/{rankingFacet}

Path Parameters

Name Type Description

Name	Type	Description
`rankingFacet`	enum	Example: city_name Must be one of: `certifications`, `certifications_name`, `cip2`, `cip2_name`, `cip4`, `cip4_name`, `cip6`, `cip6_name`, `city`, `city_name`, `common_skills`, `common_skills_name`, `company`, `company_name`, `county`, `county_name`, `edulevels`, `edulevels_name`, `fips`, `fips_name`, `gender`, `gender_name`, `grad_year`, `max_edulevels`, `max_edulevels_name`, `moves_in_most_recent_company`, `moves_in_previous_company`, `msa`, `msa_name`, `most_recent_company`, `most_recent_company_end_date`, `most_recent_company_start_date`, `naics2`, `naics2_name`, `naics3`, `naics3_name`, `naics4`, `naics4_name`, `naics5`, `naics5_name`, `naics6`, `naics6_name`, `onet`, `onet_name`, `previous_company`, `previous_company_end_date`, `previous_company_start_date`, `schools`, `schools_ipeds`, `schools_name`, `skill_categories`, `skill_categories_name`, `skill_subcategories`, `skill_subcategories_name`, `skills`, `skills_name`, `soc2`, `soc2_name`, `soc3`, `soc3_name`, `soc4`, `soc4_name`, `soc5`, `soc5_name`, `software_skills`, `software_skills_name`, `specialized_skills`, `specialized_skills_name`, `state`, `state_name`, `title`, `title_name`, `years_in_current_role`, `years_with_most_recent_company`, `years_with_previous_company`, `revenue_bucket`, `employee_count_range`

rankingFacet

enum

Example: city_name

Must be one of: certifications, certifications_name, cip2, cip2_name, cip4, cip4_name, cip6, cip6_name, city, city_name, common_skills, common_skills_name, company, company_name, county, county_name, edulevels, edulevels_name, fips, fips_name, gender, gender_name, grad_year, max_edulevels, max_edulevels_name, moves_in_most_recent_company, moves_in_previous_company, msa, msa_name, most_recent_company, most_recent_company_end_date, most_recent_company_start_date, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, onet, onet_name, previous_company, previous_company_end_date, previous_company_start_date, schools, schools_ipeds, schools_name, skill_categories, skill_categories_name, skill_subcategories, skill_subcategories_name, skills, skills_name, soc2, soc2_name, soc3, soc3_name, soc4, soc4_name, soc5, soc5_name, software_skills, software_skills_name, specialized_skills, specialized_skills_name, state, state_name, title, title_name, years_in_current_role, years_with_most_recent_company, years_with_previous_company, revenue_bucket, employee_count_range

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

{
  "filter": {
    "last_updated": {
      "start": "2018",
      "end": "2019"
    },
    "skills_name": {
      "include": [
        "C++ (Programming Language)"
      ]
    },
    "educations": {
      "schools_name": [
        "University of California, Davis"
      ]
    }
  },
  "rank": {
    "by": "profiles",
    "limit": 5,
    "extra_metrics": [
      "unique_schools"
    ],
    "min_profiles": 1
  }
}

Code Examples

curl --request POST \
  --url https://api.lightcast.io/profiles/rankings/{rankingFacet} \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "last_updated": { "start": "2018", "end": "2019" }, "skills_name": { "include": [ "C++ (Programming Language)" ] }, "educations": { "schools_name": [ "University of California, Davis" ] } }, "rank": { "by": "profiles", "limit": 5, "extra_metrics": [ "unique_schools" ], "min_profiles": 1 } }'

Response Examples

{
  "data": {
    "ranking": {
      "buckets": [
        {
          "name": "San Francisco, CA",
          "profiles": 95,
          "unique_schools": 57
        },
        {
          "name": "Davis, CA",
          "profiles": 73,
          "unique_schools": 44
        },
        {
          "name": "Sacramento, CA",
          "profiles": 35,
          "unique_schools": 20
        },
        {
          "name": "San Jose, CA",
          "profiles": 13,
          "unique_schools": 10
        },
        {
          "name": "Los Angeles, CA",
          "profiles": 11,
          "unique_schools": 11
        },
        {
          "name": "San Diego, CA",
          "profiles": 7,
          "unique_schools": 4
        },
        {
          "name": "New York, NY",
          "profiles": 6,
          "unique_schools": 12
        },
        {
          "name": "Fremont, CA",
          "profiles": 4,
          "unique_schools": 4
        },
        {
          "name": "Campbell, CA",
          "profiles": 3,
          "unique_schools": 3
        },
        {
          "name": "Castro Valley, CA",
          "profiles": 3,
          "unique_schools": 2
        },
        {
          "name": "Milpitas, CA",
          "profiles": 3,
          "unique_schools": 1
        },
        {
          "name": "Oakland, CA",
          "profiles": 3,
          "unique_schools": 4
        },
        {
          "name": "Orange, CA",
          "profiles": 3,
          "unique_schools": 9
        },
        {
          "name": "Palo Alto, CA",
          "profiles": 3,
          "unique_schools": 5
        },
        {
          "name": "Santa Clara, CA",
          "profiles": 3,
          "unique_schools": 5
        },
        {
          "name": "Washington, DC",
          "profiles": 3,
          "unique_schools": 7
        },
        {
          "name": "Berkeley, CA",
          "profiles": 2,
          "unique_schools": 4
        },
        {
          "name": "Cupertino, CA",
          "profiles": 2,
          "unique_schools": 2
        },
        {
          "name": "Dublin, CA",
          "profiles": 2,
          "unique_schools": 3
        },
        {
          "name": "Elk Grove, CA",
          "profiles": 2,
          "unique_schools": 2
        }
      ],
      "facet": "city_name",
      "limit": 20,
      "rank_by": "profiles"
    },
    "totals": {
      "profiles": 344,
      "unique_schools": 164
    }
  }
}

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

//Your request wasn't valid (bad keyword expression).

{
  "errors": [
    {
      "status": 422,
      "title": "Invalid request content",
      "detail": "Invalid keyword search expression syntax:\n\t\"general merchandise\" OR \"apparel\" OR \"grocery\" OR\n\t                                                  ^"
    }
  ]
}

`POST` /rankings/{rankingFacet}/rankings/{nestedRankingFacet}

Get a nested ranking (e.g. top companies, then top skills per company).

Path Parameters

Name Type Description

Name	Type	Description
`rankingFacet`	enum	Example: city_name Must be one of: `certifications`, `certifications_name`, `cip2`, `cip2_name`, `cip4`, `cip4_name`, `cip6`, `cip6_name`, `city`, `city_name`, `common_skills`, `common_skills_name`, `company`, `company_name`, `county`, `county_name`, `edulevels`, `edulevels_name`, `fips`, `fips_name`, `gender`, `gender_name`, `grad_year`, `max_edulevels`, `max_edulevels_name`, `moves_in_most_recent_company`, `moves_in_previous_company`, `msa`, `msa_name`, `most_recent_company`, `most_recent_company_end_date`, `most_recent_company_start_date`, `naics2`, `naics2_name`, `naics3`, `naics3_name`, `naics4`, `naics4_name`, `naics5`, `naics5_name`, `naics6`, `naics6_name`, `onet`, `onet_name`, `previous_company`, `previous_company_end_date`, `previous_company_start_date`, `schools`, `schools_ipeds`, `schools_name`, `skill_categories`, `skill_categories_name`, `skill_subcategories`, `skill_subcategories_name`, `skills`, `skills_name`, `soc2`, `soc2_name`, `soc3`, `soc3_name`, `soc4`, `soc4_name`, `soc5`, `soc5_name`, `software_skills`, `software_skills_name`, `specialized_skills`, `specialized_skills_name`, `state`, `state_name`, `title`, `title_name`, `years_in_current_role`, `years_with_most_recent_company`, `years_with_previous_company`, `revenue_bucket`, `employee_count_range`
`nestedRankingFacet`	enum	Example: title_name Must be one of: `certifications`, `certifications_name`, `city`, `cip2`, `cip2_name`, `cip4`, `cip4_name`, `cip6`, `cip6_name`, `city_name`, `common_skills`, `common_skills_name`, `company`, `company_name`, `contract_type`, `contract_type_name`, `county`, `county_name`, `edulevels`, `edulevels_name`, `employment_type`, `employment_type_name`, `fips`, `fips_name`, `lot_career_area`, `lot_career_area_name`, `lot_occupation`, `lot_occupation_name`, `lot_occupation_group`, `lot_occupation_group_name`, `lot_specialized_occupation`, `lot_specialized_occupation_name`, `lightcast_sectors`, `lightcast_sectors_name`, `max_years_experience`, `min_years_experience`, `min_edulevels`, `min_edulevels_name`, `max_edulevels`, `max_edulevels_name`, `msa`, `msa_name`, `msa_skill_cluster`, `naics2`, `naics2_name`, `naics3`, `naics3_name`, `naics4`, `naics4_name`, `naics5`, `naics5_name`, `naics6`, `naics6_name`, `national_skill_cluster`, `onet`, `onet_name`, `remote_type`, `remote_type_name`, `skill_categories`, `skill_categories_name`, `skill_subcategories`, `skill_subcategories_name`, `skills`, `skills_name`, `soc2`, `soc2_name`, `soc3`, `soc3_name`, `soc4`, `soc4_name`, `soc5`, `soc5_name`, `software_skills`, `software_skills_name`, `sources`, `source_types`, `specialized_occupation_name`, `specialized_skills`, `specialized_skills_name`, `state`, `state_name`, `state_skill_cluster`, `title`, `title_name`, `job_seniority`, `job_seniority_name`

rankingFacet

enum

Example: city_name

nestedRankingFacet

enum

Example: title_name

Must be one of: certifications, certifications_name, city, cip2, cip2_name, cip4, cip4_name, cip6, cip6_name, city_name, common_skills, common_skills_name, company, company_name, contract_type, contract_type_name, county, county_name, edulevels, edulevels_name, employment_type, employment_type_name, fips, fips_name, lot_career_area, lot_career_area_name, lot_occupation, lot_occupation_name, lot_occupation_group, lot_occupation_group_name, lot_specialized_occupation, lot_specialized_occupation_name, lightcast_sectors, lightcast_sectors_name, max_years_experience, min_years_experience, min_edulevels, min_edulevels_name, max_edulevels, max_edulevels_name, msa, msa_name, msa_skill_cluster, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, national_skill_cluster, onet, onet_name, remote_type, remote_type_name, skill_categories, skill_categories_name, skill_subcategories, skill_subcategories_name, skills, skills_name, soc2, soc2_name, soc3, soc3_name, soc4, soc4_name, soc5, soc5_name, software_skills, software_skills_name, sources, source_types, specialized_occupation_name, specialized_skills, specialized_skills_name, state, state_name, state_skill_cluster, title, title_name, job_seniority, job_seniority_name

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`	num	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

{
  "filter": {
    "last_updated": {
      "start": "2025-01",
      "end": "2025-12"
    }
  },
  "rank": {
    "by": "profiles",
    "limit": 5,
    "extra_metrics": [
      "unique_schools"
    ]
  },
  "nested_rank": {
    "by": "significance",
    "limit": 5
  }
}

Code Examples

curl --request POST \
  --url https://api.lightcast.io/profiles/rankings/{rankingFacet}/rankings/{nestedRankingFacet} \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "last_updated": { "start": "2025-01", "end": "2025-12" } }, "rank": { "by": "profiles", "limit": 5, "extra_metrics": [ "unique_schools" ] }, "nested_rank": { "by": "significance", "limit": 5 } }'

Response Examples

{
  "data": {
    "ranking": {
      "buckets": [
        {
          "name": "Los Angeles, CA",
          "ranking": {
            "buckets": [
              {
                "name": "Event Planner",
                "profiles": 1,
                "significance": 7.8
              },
              {
                "name": "Real Estate Agent",
                "profiles": 1,
                "significance": 7.8
              },
              {
                "name": "Marketing Specialist (General)",
                "profiles": 1,
                "significance": 7.8
              },
              {
                "name": "Department Manager",
                "profiles": 1,
                "significance": 3.8
              },
              {
                "name": "Owner / Founder",
                "profiles": 1,
                "significance": 1.4
              }
            ],
            "facet": "lot_specialized_occupation_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "significance": 0,
          "unique_schools": 4
        },
        {
          "name": "New York, NY",
          "ranking": {
            "buckets": [
              {
                "name": "Chemical Technician",
                "profiles": 1,
                "significance": 7.8
              },
              {
                "name": "Data Manager",
                "profiles": 1,
                "significance": 7.8
              },
              {
                "name": "English / Language Arts Teacher",
                "profiles": 1,
                "significance": 3.8
              },
              {
                "name": "Executive Assistant",
                "profiles": 1,
                "significance": 2.5
              },
              {
                "name": "Owner / Founder",
                "profiles": 1,
                "significance": 1.4
              }
            ],
            "facet": "lot_specialized_occupation_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "significance": 0,
          "unique_schools": 1
        },
        {
          "name": "[Unknown City], ",
          "ranking": {
            "buckets": [
              {
                "name": ".NET Developer / Engineer",
                "profiles": 1,
                "significance": 12.2
              },
              {
                "name": "Software Developer / Engineer",
                "profiles": 1,
                "significance": 6
              },
              {
                "name": "Clinical Supervisor / Manager",
                "profiles": 1,
                "significance": 3.9
              },
              {
                "name": "Project Manager (General)",
                "profiles": 1,
                "significance": 3.9
              }
            ],
            "facet": "lot_specialized_occupation_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "significance": 0,
          "unique_schools": 6
        },
        {
          "name": "Kansas City, MO",
          "ranking": {
            "buckets": [
              {
                "name": "Systems Engineer",
                "profiles": 1,
                "significance": 49.2
              },
              {
                "name": "Distribution Manager",
                "profiles": 1,
                "significance": 49.2
              }
            ],
            "facet": "lot_specialized_occupation_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "significance": 0,
          "unique_schools": 3
        },
        {
          "name": "[Unknown City], NY",
          "ranking": {
            "buckets": [
              {
                "name": "Director of Sales",
                "profiles": 1,
                "significance": 49.2
              },
              {
                "name": "Producer",
                "profiles": 1,
                "significance": 16.1
              }
            ],
            "facet": "lot_specialized_occupation_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "significance": 0,
          "unique_schools": 0
        }
      ],
      "facet": "city_name",
      "limit": 5,
      "rank_by": "significance"
    },
    "totals": {
      "unique_schools": 79
    }
  }
}

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

//Your request wasn't valid (bad keyword expression).

{
  "errors": [
    {
      "status": 422,
      "title": "Invalid request content",
      "detail": "Invalid keyword search expression syntax:\n\t\"general merchandise\" OR \"apparel\" OR \"grocery\" OR\n\t                                                  ^"
    }
  ]
}

/rankings

GET /rankings

Code Examples

Response Examples

POST /rankings/{rankingFacet}

Path Parameters

Query Parameters

Request Body

Code Examples

Response Examples

POST /rankings/{rankingFacet}/rankings/{nestedRankingFacet}

Path Parameters

Query Parameters

Request Body

Code Examples

Response Examples

`GET` /rankings

`POST` /rankings/{rankingFacet}

`POST` /rankings/{rankingFacet}/rankings/{nestedRankingFacet}