Status Page
API Reference

Endpoint Examples

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

Response Examples

{
  "data": [
    "certifications",
    "certifications_name",
    "city",
    "city_name",
    "common_skills",
    "common_skills_name",
    "company",
    "company_name",
    "gender",
    "gender_name",
    "grad_year",
    "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",
    "naics2",
    "naics2_name",
    "naics3",
    "naics3_name",
    "naics4",
    "naics4_name",
    "naics5",
    "naics5_name",
    "naics6",
    "naics6_name",
    "noc1",
    "noc1_name",
    "noc2",
    "noc2_name",
    "noc3",
    "noc3_name",
    "noc4",
    "noc4_name",
    "noc5",
    "noc5_name",
    "schools",
    "schools_ipeds",
    "schools_name",
    "skill_categories",
    "skill_categories_name",
    "skill_subcategories",
    "skill_subcategories_name",
    "skills",
    "skills_name",
    "software_skills",
    "software_skills_name",
    "specialized_skills",
    "specialized_skills_name",
    "title",
    "title_name",
    "cma",
    "cma_name",
    "cd",
    "cd_name",
    "csd",
    "csd_name",
    "pr",
    "pr_name",
    "province",
    "province_name"
  ]
}

POST /rankings/[rankingFacet]

Path Parameters

NameTypeDescription
rankingFacetenum

Example: title_name

Must be one of: cd, cd_name, certifications, certifications_name, cip2, cip2_name, cip4, cip4_name, cip6, cip6_name, city, city_name, cma, cma_name, common_skills, common_skills_name, company, company_name, csd, csd_name, edulevels, edulevels_name, gender, gender_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, most_recent_company, most_recent_company_end_date, most_recent_company_start_date, moves_in_most_recent_company, moves_in_previous_company, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, noc1, noc1_name, noc2, noc2_name, noc3, noc3_name, noc4, noc4_name, noc5, noc5_name, pr, pr_name, previous_company, previous_company_end_date, previous_company_start_date, province, province_name, schools, schools_ipeds, schools_name, skill_categories, skill_categories_name, skill_subcategories, skill_subcategories_name, skills, skills_name, software_skills, software_skills_name, specialized_skills, specialized_skills_name, title, title_name, years_in_current_role, years_of_work_history, years_with_most_recent_company, years_with_previous_company

Query Parameters

NameTypeDescription
title_versionenum

Specify Job Title taxonomy version to use.
This parameter is optional.

Default: emsi
Must be one of: emsi

company_versionenum

Specify company taxonomy version to use.
This parameter is optional.

Default: emsi_company

Must be one of: emsi_company

naics_versionenumSpecify NAICS taxonomy version to use.
This parameter is optional.
Default: naics_std_2017
Must be one of: naics_std_2017, naics_std_2022
cip_versionenum

Specify CIP taxonomy version to use.
This parameter is optional.

Default: cip2020

Must be one of: cip2010, cip2020

cip_standard_versionenum

Specify CIP standard taxonomy version to use.

This parameter is optional.

Default: 2020.0.0
Must be one of: 2010.0.1, 2020.0.0

new_taxonomy_versionsenum

Use new taxonomy versions.
This parameter is optional.

Must be one of: true, false

lot_versionenum

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": "2024"
    },
    "skills_name": {
      "include": [
        "Training And Development"
      ]
    }
  },
  "rank": {
    "by": "profiles",
    "limit": 5,
    "extra_metrics": [
      "unique_schools"
    ],
    "min_profiles": 1
  }
}

Code Examples

curl --request POST \
  --url https://api.lightcast.io/ca-profiles/rankings/{rankingFacet} \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "last_updated": { "start": "2018", "end": "2024" }, "skills_name": { "include": [ "Training And Development" ] } }, "rank": { "by": "profiles", "limit": 5, "extra_metrics": [ "unique_schools" ], "min_profiles": 1 } }'

Response Examples

{
  "data": {
    "ranking": {
      "buckets": [
        {
          "name": "Unclassified",
          "profiles": 12780,
          "unique_schools": 2593
        },
        {
          "name": "Teachers",
          "profiles": 3240,
          "unique_schools": 805
        },
        {
          "name": "Human Resources Managers",
          "profiles": 3198,
          "unique_schools": 1036
        },
        {
          "name": "Owners",
          "profiles": 2964,
          "unique_schools": 911
        },
        {
          "name": "Presidents",
          "profiles": 2865,
          "unique_schools": 1299
        }
      ],
      "facet": "title_name",
      "limit": 5,
      "rank_by": "profiles"
    },
    "totals": {
      "profiles": 253574,
      "unique_schools": 11222
    }
  }
}
// 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 /rankings/{rankingFacet}/rankings/{nestedRankingFacet}

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

Path Parameters

NameTypeDescription
rankingFacetenum

Example: title_name

Must be one of: cd, cd_name, certifications, certifications_name, cip2, cip2_name, cip4, cip4_name, cip6, cip6_name, city, city_name, cma, cma_name, common_skills, common_skills_name, company, company_name, csd, csd_name, edulevels, edulevels_name, gender, gender_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, most_recent_company, most_recent_company_end_date, most_recent_company_start_date, moves_in_most_recent_company, moves_in_previous_company, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, noc1, noc1_name, noc2, noc2_name, noc3, noc3_name, noc4, noc4_name, noc5, noc5_name, pr, pr_name, previous_company, previous_company_end_date, previous_company_start_date, province, province_name, schools, schools_ipeds, schools_name, skill_categories, skill_categories_name, skill_subcategories, skill_subcategories_name, skills, skills_name, software_skills, software_skills_name, specialized_skills, specialized_skills_name, title, title_name, years_in_current_role, years_of_work_history, years_with_most_recent_company, years_with_previous_company

nestedRankingFacetenum

Example: title_name

Must be one of: cd, cd_name, certifications, certifications_name, cip2, cip2_name, cip4, cip4_name, cip6, cip6_name, city, city_name, cma, cma_name, common_skills, common_skills_name, company, company_name, csd, csd_name, edulevels, edulevels_name, gender, gender_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, most_recent_company, most_recent_company_end_date, most_recent_company_start_date, moves_in_most_recent_company, moves_in_previous_company, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, noc1, noc1_name, noc2, noc2_name, noc3, noc3_name, noc4, noc4_name, noc5, noc5_name, pr, pr_name, previous_company, previous_company_end_date, previous_company_start_date, province, province_name, schools, schools_ipeds, schools_name, skill_categories, skill_categories_name, skill_subcategories, skill_subcategories_name, skills, skills_name, software_skills, software_skills_name, specialized_skills, specialized_skills_name, title, title_name, years_in_current_role, years_of_work_history, years_with_most_recent_company, years_with_previous_company

Query Parameters

NameTypeDescription
title_versionenum

Specify Job Title taxonomy version to use.
This parameter is optional.

Default: emsi

Must be one of: emsi

company_versionenum

Specify company taxonomy version to use.
This parameter is optional.

Default: emsi_company

Must be one of: emsi_company

naics_versionenum

Specify NAICS taxonomy version to use.
This parameter is optional.

Default: naics_std_2017

Must be one of: naics_std_2017, naics_std_2022

cip_versionenum

Specify CIP taxonomy version to use.
This parameter is optional.

Default: cip2020

Must be one of: cip2010, cip2020

cip_standard_versionenum

Specify CIP standard taxonomy version to use.
This parameter is optional.

Default: 2020.0.0

Must be one of: 2010.0.1, 2020.0.0

new_taxonomy_versionsenum

Use new taxonomy versions.
This parameter is optional.

Must be one of: true, false

lot_versionenumSpecify 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/ca-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                                                  ^"
    }
  ]
}

Updated 11 days ago

Did this page help you?

Updated 11 days ago

Did this page help you?