Status Page
API Reference

Endpoint Examples

/rankings

Group and rank postings by available facets.

GET /rankings

Get a list of current available ranking facets.

Code Examples

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

Response Examples

{
  "data": [
    "active_sources_info",
    "benefit",
    "benefit_categories",
    "benefit_categories_name",
    "benefit_name",
    "certifications",
    "certifications_name",
    "cip2",
    "cip4",
    "cip6",
    "cip2_name",
    "cip4_name",
    "cip6_name",
    "city",
    "city_name",
    "common_skills",
    "common_skills_name",
    "company",
    "company_name",
    "contract_type",
    "contract_type_name",
    "county",
    "county_name",
    "edulevels",
    "edulevels_name",
    "employee_count_range",
    "employment_type",
    "employment_type_name",
    "fips",
    "fips_name",
    "is_fortune100",
    "is_fortune500",
    "is_fortune1000",
    "lightcast_sectors",
    "lightcast_sectors_name",
    "lot_career_area",
    "lot_career_area_name",
    "lot_occupation",
    "lot_occupation_group",
    "lot_occupation_group_name",
    "lot_occupation_name",
    "job_seniority",
    "job_seniority_name",
    "lot_specialized_occupation",
    "lot_specialized_occupation_name",
    "max_edulevels",
    "max_edulevels_name",
    "max_years_experience",
    "min_edulevels",
    "min_edulevels_name",
    "min_years_experience",
    "msa",
    "msa_name",
    "naics2",
    "naics3",
    "naics4",
    "naics5",
    "naics6",
    "naics2_name",
    "naics3_name",
    "naics4_name",
    "naics5_name",
    "naics6_name",
    "onet",
    "onet_name",
    "remote_type",
    "remote_type_name",
    "revenue_bucket",
    "soc2",
    "soc3",
    "soc4",
    "soc5",
    "soc2_name",
    "soc3_name",
    "soc4_name",
    "soc5_name",
    "skill_categories",
    "skill_categories_name",
    "skill_subcategories",
    "skill_subcategories_name",
    "skills",
    "skills_name",
    "software_skills",
    "software_skills_name",
    "sources",
    "source_types",
    "specialized_skills",
    "specialized_skills_name",
    "state",
    "state_name",
    "title",
    "title_name"
  ]
}

POST /rankings/{rankingFacet}

Group and rank postings by {rankingFacet}.

URL Parameters

NameTypeDescription
rankingFacetenum

Example: company_name

Must be one of: benefit_categories, benefit_categories_name, benefit, benefit_name, 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, is_fortune100, is_fortune500, is_fortune1000, stars_qualified, laa_admin_area_1, laa_admin_area_1_name, laa_admin_area_2, laa_admin_area_2_name, laa_country, laa_country_name, laa_metro, laa_metro_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, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, 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_skills, specialized_skills_name, state, state_name, title, title_name, revenue_bucket, employee_count_range, job_seniority, job_seniority_name

Query Parameter

NameTypeDescription
area_versionenum

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_versionenum

Specify SOC taxonomy version to use.

This parameter is optional.

Default: soc_2021

Must be one of: soc_2021

onet_versionenum

Specify ONET taxonomy version to use.

This parameter is optional.

Default: onet_2019

Must be one of: onet_2019

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_2022

Must be one of: naics_std_2022

new_taxonomy_versionsenum

Use new taxonomy versions.

This parameter is optional.

Must be one of: true, false

area_us_versionenum

Specify US Area taxonomy version to use.

This parameter is optional.

Default: 2.0.0

Must be one of: 1.0.2, 2.0.0

soc_lightcast_versionenum

Specify SOC Lightcast taxonomy version to use.

This parameter is optional.

Default: 2018.2021.0

Must be one of: 2018.2021.0

onet_standard_versionenum

Specify ONET Standard taxonomy version to use.

This parameter is optional.

Default: 2019.0.0

Must be one of: 2019.0.0

lot_versionenum

Specify LOT taxonomy version to use.

This parameter is optional.

Default: 7

Must be one of: 6, 7

Request Body

{
  "filter": {
    "when": {
      "start": "2020-01",
      "end": "2020-12"
    },
    "city_name": [
      "Scranton, PA"
    ]
  },
  "rank": {
    "by": "unique_postings",
    "limit": 5,
    "extra_metrics": [
      "duplicate_postings"
    ]
  }
}

Code Examples

curl --request POST \
  --url https://api.lightcast.io/jpa/rankings/company_name \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "when": { "start": "2020-01", "end": "2020-12" }, "city_name": [ "Scranton, PA" ] }, "rank": { "by": "unique_postings", "limit": 5, "extra_metrics": [ "duplicate_postings" ] } }'

Response Examples

{
  "data": {
    "ranking": {
      "buckets": [
        {
          "duplicate_postings": 6559,
          "name": "Geisinger Inc",
          "unique_postings": 722
        },
        {
          "duplicate_postings": 2938,
          "name": "Community Health Systems, Inc.",
          "unique_postings": 590
        },
        {
          "duplicate_postings": 4381,
          "name": "Army National Guard",
          "unique_postings": 320
        },
        {
          "duplicate_postings": 217,
          "name": "Soliant Health, Inc",
          "unique_postings": 263
        },
        {
          "duplicate_postings": 442,
          "name": "Allied Services, L.L.C.",
          "unique_postings": 202
        }
      ],
      "facet": "company_name",
      "limit": 5,
      "rank_by": "unique_postings"
    },
    "totals": {
      "duplicate_postings": 85990,
      "unique_postings": 20023
    }
  }
}
//Your request wasn't valid (bad parameter names or values).

{
  "errors": [
    {
      "status": 400,
      "title": "Malformed Request",
      "detail": "Expected array"
    }
  ]
}
//Your request wasn't unauthorized.

{
  "errors": [
    {
      "status": 401,
      "title": "Unauthorized Request",
      "detail": "You are not authorized to access this resource."
    }
  ]
}
//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}/timeseries

Group and rank postings by {rankingFacet} with a monthly or daily timeseries for each ranked group. Use YYYY-MM date format in the timeseries time-frame filter, timeseries.when, to get monthly summary of each ranked group, or use YYYY-MM-DD date format for daily summary.

URL Parameters

NameTypeDescription
rankingFacetenum

Example: company_name

Must be one of: benefit_categories, benefit_categories_name, benefit, benefit_name, 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, is_fortune100, is_fortune500, is_fortune1000, stars_qualified, laa_admin_area_1, laa_admin_area_1_name, laa_admin_area_2, laa_admin_area_2_name, laa_country, laa_country_name, laa_metro, laa_metro_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, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, 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_skills, specialized_skills_name, state, state_name, title, title_name, revenue_bucket, employee_count_range, job_seniority, job_seniority_name

Query Parameters

NameTypeDescription
area_versionenum

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_versionenum

Specify SOC taxonomy version to use.

This parameter is optional.

Default: soc_2021

Must be one of: soc_2021

onet_versionenum

Specify ONET taxonomy version to use.

This parameter is optional.

Default: onet_2019

Must be one of: onet_2019

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_2022

Must be one of: naics_std_2022

new_taxonomy_versionsenum

Use new taxonomy versions.

This parameter is optional.

Must be one of: true, false

area_us_versionenum

Specify US Area taxonomy version to use.

This parameter is optional.

Default: 2.0.0

Must be one of: 1.0.2, 2.0.0

soc_lightcast_versionenum

Specify SOC Lightcast taxonomy version to use.

This parameter is optional.

Default: 2018.2021.0

Must be one of: 2018.2021.0

onet_standard_versionenum

Specify ONET Standard taxonomy version to use.

This parameter is optional.

Default: 2019.0.0

Must be one of: 2019.0.0

lot_versionenum

Specify LOT taxonomy version to use.

This parameter is optional.

Default: 7

Must be one of: 6, 7

Request Body

{
  "filter": {
    "when": {
      "start": "2020-01",
      "end": "2020-12"
    },
    "city_name": [
      "Scranton, PA"
    ]
  },
  "rank": {
    "by": "unique_postings",
    "limit": 5,
    "extra_metrics": [
      "duplicate_postings"
    ]
  },
  "timeseries": {
    "when": {
      "start": "2020-01-15",
      "end": "2020-01-20"
    },
    "metrics": [
      "unique_postings"
    ]
  }
}

Code Examples

curl --request POST \
  --url https://api.lightcast.io/jpa/rankings/company_name/timeseries \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "when": { "start": "2020-01", "end": "2020-12" }, "city_name": [ "Scranton, PA" ] }, "rank": { "by": "unique_postings", "limit": 5, "extra_metrics": [ "duplicate_postings" ] }, "timeseries": { "when": { "start": "2020-01-15", "end": "2020-01-20" }, "metrics": [ "unique_postings" ] } }'

Response Examples

{
  "data": {
    "ranking": {
      "buckets": [
        {
          "duplicate_postings": 6559,
          "name": "Geisinger Inc",
          "timeseries": {
            "day": [
              "2020-01-15",
              "2020-01-16",
              "2020-01-17",
              "2020-01-18",
              "2020-01-19",
              "2020-01-20"
            ],
            "unique_postings": [
              189,
              190,
              196,
              196,
              201,
              200
            ]
          },
          "unique_postings": 722
        },
        {
          "duplicate_postings": 2938,
          "name": "Community Health Systems, Inc.",
          "timeseries": {
            "day": [
              "2020-01-15",
              "2020-01-16",
              "2020-01-17",
              "2020-01-18",
              "2020-01-19",
              "2020-01-20"
            ],
            "unique_postings": [
              139,
              137,
              138,
              142,
              143,
              143
            ]
          },
          "unique_postings": 590
        },
        {
          "duplicate_postings": 4381,
          "name": "Army National Guard",
          "timeseries": {
            "day": [
              "2020-01-15",
              "2020-01-16",
              "2020-01-17",
              "2020-01-18",
              "2020-01-19",
              "2020-01-20"
            ],
            "unique_postings": [
              84,
              85,
              85,
              85,
              86,
              85
            ]
          },
          "unique_postings": 320
        },
        {
          "duplicate_postings": 217,
          "name": "Soliant Health, Inc",
          "timeseries": {
            "day": [
              "2020-01-15",
              "2020-01-16",
              "2020-01-17",
              "2020-01-18",
              "2020-01-19",
              "2020-01-20"
            ],
            "unique_postings": [
              46,
              44,
              44,
              46,
              46,
              46
            ]
          },
          "unique_postings": 263
        },
        {
          "duplicate_postings": 442,
          "name": "Allied Services, L.L.C.",
          "timeseries": {
            "day": [
              "2020-01-15",
              "2020-01-16",
              "2020-01-17",
              "2020-01-18",
              "2020-01-19",
              "2020-01-20"
            ],
            "unique_postings": [
              76,
              77,
              78,
              78,
              78,
              78
            ]
          },
          "unique_postings": 202
        }
      ],
      "facet": "company_name",
      "limit": 5,
      "rank_by": "unique_postings"
    },
    "totals": {
      "duplicate_postings": 85990,
      "unique_postings": 20023
    }
  }
}
//Your request wasn't valid (bad parameter names or values).

{
  "errors": [
    {
      "status": 400,
      "title": "Malformed Request",
      "detail": "Expected array"
    }
  ]
}
//Your request wasn't unauthorized.

{
  "errors": [
    {
      "status": 401,
      "title": "Unauthorized Request",
      "detail": "You are not authorized to access this resource."
    }
  ]
}
//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}/distributions/{distributionFacet}

Group and rank postings by {rankingFacet} with a distribution for each ranked item.

URL Parameters

NameTypeDescription
rankingFacetenumExample: company_name
Must be one of: benefit_categories, benefit_categories_name, benefit, benefit_name, 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, is_fortune100, is_fortune500, is_fortune1000, stars_qualified, laa_admin_area_1, laa_admin_area_1_name, laa_admin_area_2, laa_admin_area_2_name, laa_country, laa_country_name, laa_metro, laa_metro_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, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, 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_skills, specialized_skills_name, state, state_name, title, title_name, revenue_bucket, employee_count_range, job_seniority, job_seniority_name
distributionFacetenum

Example: salary

Must be one of: max_years_experience, min_years_experience, posting_duration, salary

Query Parameters

NameTypeDescription
area_versionenum

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_versionenum

Specify SOC taxonomy version to use.

This parameter is optional.

Default: soc_2021

Must be one of: soc_2021

onet_versionenum

Specify ONET taxonomy version to use.

This parameter is optional.

Default: onet_2019

Must be one of: onet_2019

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_2022

Must be one of: naics_std_2022

new_taxonomy_versionsenum

Use new taxonomy versions.

This parameter is optional.

Must be one of: true, false

area_us_versionenum

Specify US Area taxonomy version to use.

This parameter is optional.

Default: 2.0.0

Must be one of: 1.0.2, 2.0.0

soc_lightcast_versionenum

Specify SOC Lightcast taxonomy version to use.

This parameter is optional.

Default: 2018.2021.0

Must be one of: 2018.2021.0

onet_standard_versionenum

Specify ONET Standard taxonomy version to use.

This parameter is optional.

Default: 2019.0.0

Must be one of: 2019.0.0

lot_versionenum

Specify LOT taxonomy version to use.

This parameter is optional.

Default: 7

Must be one of: 6, 7

Request Body

{
  "filter": {
    "when": {
      "start": "2020-01",
      "end": "2023-12"
    }
  },
  "rank": {
    "by": "unique_postings",
    "limit": 2
  },
  "distribution": {
    "type": "histogram",
    "options": {
      "interval": 100000
    },
    "metrics": [
      "duplicate_postings"
    ]
  }
}

Code Examples

curl --request POST \
  --url https://api.lightcast.io/jpa/rankings/company_name/distributions/salary \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "when": { "start": "2020-01", "end": "2023-12" } }, "rank": { "by": "unique_postings", "limit": 2 }, "distribution": { "type": "histogram", "options": { "interval": 100000 }, "metrics": [ "duplicate_postings" ] } }'

Response Examples

{
  "data": {
    "ranking": {
      "buckets": [
        {
          "distribution": {
            "buckets": [
              {
                "duplicate_postings": 13156784,
                "key": 1,
                "value": 0
              },
              {
                "duplicate_postings": 2464553,
                "key": 2,
                "value": 100000
              },
              {
                "duplicate_postings": 187126,
                "key": 3,
                "value": 200000
              },
              {
                "duplicate_postings": 41355,
                "key": 4,
                "value": 300000
              },
              {
                "duplicate_postings": 8025,
                "key": 5,
                "value": 400000
              },
              {
                "duplicate_postings": 2780,
                "key": 6,
                "value": 500000
              }
            ],
            "domain": {
              "max": 500000,
              "min": 15100
            },
            "facet": "salary",
            "interval": 100000,
            "type": "histogram"
          },
          "name": "Unclassified",
          "unique_postings": 18621508
        },
        {
          "distribution": {
            "buckets": [
              {
                "duplicate_postings": 5650866,
                "key": 1,
                "value": 0
              },
              {
                "duplicate_postings": 17838,
                "key": 2,
                "value": 100000
              },
              {
                "duplicate_postings": 1490,
                "key": 3,
                "value": 200000
              },
              {
                "duplicate_postings": 183,
                "key": 4,
                "value": 300000
              },
              {
                "duplicate_postings": 8,
                "key": 5,
                "value": 400000
              },
              {
                "duplicate_postings": 69,
                "key": 6,
                "value": 500000
              }
            ],
            "domain": {
              "max": 500000,
              "min": 17680
            },
            "facet": "salary",
            "interval": 100000,
            "type": "histogram"
          },
          "name": "Amazon",
          "unique_postings": 1257477
        }
      ],
      "facet": "company_name",
      "limit": 2,
      "rank_by": "unique_postings"
    },
    "totals": {
      "unique_postings": 163400492
    }
  }
}
//Your request wasn't valid (bad parameter names or values).

{
  "errors": [
    {
      "status": 400,
      "title": "Malformed Request",
      "detail": "Expected array"
    }
  ]
}
//Your request wasn't unauthorized.

{
  "errors": [
    {
      "status": 401,
      "title": "Unauthorized Request",
      "detail": "You are not authorized to access this resource."
    }
  ]
}
//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).

URL Parameters

NameTypeDescription
rankingFacetenumExample: company_name
Must be one of: benefit_categories, benefit_categories_name, benefit, benefit_name, 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, is_fortune100, is_fortune500, is_fortune1000, stars_qualified, laa_admin_area_1, laa_admin_area_1_name, laa_admin_area_2, laa_admin_area_2_name, laa_country, laa_country_name, laa_metro, laa_metro_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, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, 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_skills, specialized_skills_name, state, state_name, title, title_name, revenue_bucket, employee_count_range, job_seniority, job_seniority_name
nestedRankingFacetenumExample: title_name
Must be one of: benefit_categories, benefit_categories_name, benefit, benefit_name, 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, is_fortune100, is_fortune500, is_fortune1000, stars_qualified, laa_admin_area_1, laa_admin_area_1_name, laa_admin_area_2, laa_admin_area_2_name, laa_country, laa_country_name, laa_metro, laa_metro_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, naics2, naics2_name, naics3, naics3_name, naics4, naics4_name, naics5, naics5_name, naics6, naics6_name, 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_skills, specialized_skills_name, state, state_name, title, title_name, revenue_bucket, employee_count_range, job_seniority, job_seniority_name

Query Parameters

NameTypeDescription
area_versionenum

Specify US Area taxonomy version to use.

This parameter is optional.

efault: us_area_2024_4

Must be one of: us_area_2024_3, us_area_2024_4

soc_versionenum

Specify SOC taxonomy version to use.

This parameter is optional.

Default: soc_2021

Must be one of: soc_2021

onet_versionenum

Specify ONET taxonomy version to use.

This parameter is optional.
Default: onet_2019

Must be one of: onet_2019

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_2022

Must be one of: naics_std_2022

new_taxonomy_versionsenum

Use new taxonomy versions.

This parameter is optional.

Must be one of: true, false

area_us_versionenum

Specify US Area taxonomy version to use.

This parameter is optional.

Default: 2.0.0

Must be one of: 1.0.2, 2.0.0

soc_lightcast_versionenum

Specify SOC Lightcast taxonomy version to use.

This parameter is optional.

Default: 2018.2021.0

Must be one of: 2018.2021.0

onet_standard_versionenum

Specify ONET Standard taxonomy version to use.

This parameter is optional.

Default: 2019.0.0

Must be one of: 2019.0.0

lot_versionenum

Specify LOT taxonomy version to use.

This parameter is optional.

Default: 7

Must be one of: 6, 7

Request Body

{
  "filter": {
    "when": {
      "start": "2020-01",
      "end": "2020-12"
    },
    "city_name": [
      "Scranton, PA"
    ]
  },
  "rank": {
    "by": "unique_postings",
    "limit": 5,
    "extra_metrics": [
      "duplicate_postings"
    ]
  },
  "nested_rank": {
    "by": "significance",
    "min_unique_postings": 1,
    "limit": 5
  }
}

Code Examples

curl --request POST \
  --url https://api.lightcast.io/jpa/rankings/company_name/rankings/title_name \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "when": { "start": "2020-01", "end": "2020-12" }, "city_name": [ "Scranton, PA" ] }, "rank": { "by": "unique_postings", "limit": 5, "extra_metrics": [ "duplicate_postings" ] }, "nested_rank": { "by": "significance", "min_unique_postings": 1, "limit": 5 } }'

Response Examples

{
  "data": {
    "ranking": {
      "buckets": [
        {
          "duplicate_postings": 6559,
          "name": "Geisinger Inc",
          "ranking": {
            "buckets": [
              {
                "name": "Specialty Clinic Licensed Practical Nurses",
                "significance": 151.9881157958914,
                "unique_postings": 5
              },
              {
                "name": "Evaluation Assistants",
                "significance": 125.88211732387495,
                "unique_postings": 4
              },
              {
                "name": "Licensed Registered Nurses",
                "significance": 98.38387034949157,
                "unique_postings": 8
              },
              {
                "name": "Medical Surgical Oncology Registered Nurses",
                "significance": 94.84830283499103,
                "unique_postings": 10
              },
              {
                "name": "Operating Room Aides",
                "significance": 94.40743286825246,
                "unique_postings": 6
              }
            ],
            "facet": "title_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "unique_postings": 722
        },
        {
          "duplicate_postings": 2938,
          "name": "Community Health Systems, Inc.",
          "ranking": {
            "buckets": [
              {
                "name": "Nurse Extenders",
                "significance": 233.672283347697,
                "unique_postings": 7
              },
              {
                "name": "Courtesy Drivers",
                "significance": 133.5236292253184,
                "unique_postings": 6
              },
              {
                "name": "Behavioral Health Workers",
                "significance": 115.87300679197276,
                "unique_postings": 9
              },
              {
                "name": "Medical Services Representatives",
                "significance": 114.45415192678624,
                "unique_postings": 2
              },
              {
                "name": "Event Sales Planners",
                "significance": 66.76520444316768,
                "unique_postings": 1
              }
            ],
            "facet": "title_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "unique_postings": 590
        },
        {
          "duplicate_postings": 4381,
          "name": "Army National Guard",
          "ranking": {
            "buckets": [
              {
                "name": "Geospatial Engineers",
                "significance": 236.71707954494437,
                "unique_postings": 11
              },
              {
                "name": "Track Vehicle Repairers",
                "significance": 215.64496055403308,
                "unique_postings": 11
              },
              {
                "name": "Multi-Channel Transmission Systems Operators/Maintainers",
                "significance": 151.28722439236114,
                "unique_postings": 8
              },
              {
                "name": "Fire Support Specialists",
                "significance": 148.92609588623046,
                "unique_postings": 7
              },
              {
                "name": "Air Defense Battle Management System Operators",
                "significance": 94.2697801983173,
                "unique_postings": 3
              }
            ],
            "facet": "title_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "unique_postings": 320
        },
        {
          "duplicate_postings": 217,
          "name": "Soliant Health, Inc",
          "ranking": {
            "buckets": [
              {
                "name": "Gifted Education Teachers",
                "significance": 697.8579777290183,
                "unique_postings": 3
              },
              {
                "name": "Preschool Speech Language Pathologists",
                "significance": 226.79614314215908,
                "unique_postings": 3
              },
              {
                "name": "Coverage Specialists",
                "significance": 201.6029088175339,
                "unique_postings": 1
              },
              {
                "name": "Special Education Specialists",
                "significance": 174.45593929917473,
                "unique_postings": 3
              },
              {
                "name": "Paraprofessionals/Teaching Assistants",
                "significance": 168.0017903010501,
                "unique_postings": 1
              }
            ],
            "facet": "title_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "unique_postings": 263
        },
        {
          "duplicate_postings": 442,
          "name": "Allied Services, L.L.C.",
          "ranking": {
            "buckets": [
              {
                "name": "Transitional Interns",
                "significance": 3417.5311734143716,
                "unique_postings": 2
              },
              {
                "name": "Assistant Directors of Health Information Management",
                "significance": 1708.7655867071858,
                "unique_postings": 1
              },
              {
                "name": "Residence Assistants",
                "significance": 1708.7655867071858,
                "unique_postings": 1
              },
              {
                "name": "Skilled Nursing Registered Nurses",
                "significance": 798.1785612831718,
                "unique_postings": 16
              },
              {
                "name": "Allied Physical Therapists",
                "significance": 759.4436710997832,
                "unique_postings": 2
              }
            ],
            "facet": "title_name",
            "limit": 5,
            "rank_by": "significance"
          },
          "unique_postings": 202
        }
      ],
      "facet": "company_name",
      "limit": 5,
      "rank_by": "unique_postings"
    },
    "totals": {
      "duplicate_postings": 85990,
      "unique_postings": 20023
    }
  }
}
//Your request wasn't valid (bad parameter names or values).

{
  "errors": [
    {
      "status": 400,
      "title": "Malformed Request",
      "detail": "Expected array"
    }
  ]
}
//Your request wasn't unauthorized.

{
  "errors": [
    {
      "status": 401,
      "title": "Unauthorized Request",
      "detail": "You are not authorized to access this resource."
    }
  ]
}

//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 about 2 months ago

Did this page help you?

Updated about 2 months ago

Did this page help you?