Status Page
API Reference

Use Cases

Overview

Lightcast Global Postings APIs help you access, analyze, and explore job posting data across global labor markets. They allow you to retrieve total postings, posting trends over time, rank demand across dimensions, access individual posting records, and understand how postings are distributed across dimensions, enabling consistent, reliable insights into employer demand worldwide.

Explore the use cases below to understand how the Global Postings API can be applied in real-world scenarios.

Retrieve Total Postings

Tracking job demand across global labor markets requires a reliable way to aggregate posting activity over defined time periods and skill sets. Without a consistent method for filtering and summarizing posting data, it is difficult to measure hiring trends, assess skill demand, or benchmark posting activity across international markets.

This API enables you to retrieve aggregate job posting metrics filtered by date range and specific skills. It returns summarized figures such as unique posting counts and median posting duration, giving you a concise, high-level view of job demand for a defined skill set across global labor markets.

See the Global Postings Totals API reference for full request parameters and response details.

When to Use

  • You want to measure total job posting volume for a specific skill over a defined time period
  • You are benchmarking posting activity for a skill set across different time windows
  • You want a high-level summary of job market activity before conducting deeper analysis

Endpoint

https://api.lightcast.io/global-postings/totals

Sample Request

curl --request POST \
     --url https://api.lightcast.io/global-postings/totals \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXX ' \
     --header 'content-type: application/json' \
     --data '
{
  "filter": {
    "when": {
      "start": "2019-03",
      "end": "2019-06"
    },
    "skills": [
      "KS123X777H5WFNXQ6BPM"
    ]
  },
  "metrics": [
    "unique_postings",
    "median_posting_duration"
  ]
}
'

Sample Response

{
  "data": {
    "totals": {
      "median_posting_duration": null,
      "unique_postings": 17
    }
  }
}

Posting Trends Over Time

Measuring job demand at a single point in time does not reveal how hiring activity is shifting across global labor markets. Without a time-based view of posting activity, it is difficult to identify emerging trends, seasonal patterns, or periods of significant change in employer demand.

This API enables you to track job posting activity over time by returning monthly unique posting counts across a defined date range. It breaks down posting volume month by month alongside a cumulative total, giving you a structured view of how job demand has evolved across global labor markets.

See the Global Postings Timeseries API reference for full request parameters and response details.

When to Use

  • You want to track how job posting volume changes month over month across global labor markets
  • You need to identify hiring trends or seasonal patterns within a defined time window
  • You want to compare posting activity across different time periods to surface growth or decline in hiring

Endpoint

https://api.lightcast.io/global-postings/timeseries

Sample Request

curl --request POST \
     --url https://api.lightcast.io/global-postings/timeseries \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXX' \
     --header 'content-type: application/json' \
     --data '
{
  "filter": {
    "when": {
      "start": "2019-05",
      "end": "2019-06",
      "type": "posted"
    }
  },
  "metrics": [
    "unique_postings"
  ]
}
'

Sample Response

{
  "data": {
    "timeseries": {
      "month": [
        "2019-05",
        "2019-06"
      ],
      "unique_postings": [
        0,
        100
      ]
    },
    "totals": {
      "unique_postings": 100
    }
  }
}

Rank Postings by Dimensions

Identifying where job demand is concentrated across global labor markets requires the ability to slice posting activity by different dimensions. Without a flexible way to rank postings across dimensions such as company, occupation, or region, it is difficult to surface meaningful patterns or compare hiring activity across different segments of the labor market.

This API enables you to rank job posting activity across any supported dimension by returning a structured list of top results based on unique posting volume. Each result includes posting counts and median posting duration, giving you a consistent and comparable view of where hiring demand is strongest across whichever dimension is most relevant to your analysis.

See the Global Postings Rankings API reference for full request parameters and response details.

When to Use

  • You want to rank job posting activity across a specific dimension, such as company, occupation, or region
  • You need to identify which segments are driving the most hiring demand over a defined time period
  • You are comparing posting volume and duration across different facets to surface labor market patterns
  • You want a flexible, reusable way to analyze global job posting activity across multiple dimensions

Endpoint

https://api.lightcast.io/global-postings/rankings/{rankingFacet}

Sample Request

curl --request POST \
     --url https://api.lightcast.io/global-postings/rankings/anz_sco_1 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXX' \
     --header 'content-type: application/json' \
     --data '
{
  "filter": {
    "when": {
      "start": "2019-03",
      "end": "2019-06",
      "type": "expired"
    }
  },
  "rank": {
    "by": "unique_postings",
    "limit": 10,
    "extra_metrics": [
      "median_posting_duration"
    ]
  }
}
'

Sample Response

{
  "data": {
    "ranking": {
      "buckets": [
        {
          "median_posting_duration": 31,
          "name": "2",
          "unique_postings": 144622
        },
        {
          "median_posting_duration": 31,
          "name": "5",
          "unique_postings": 56311
        },
        {
          "median_posting_duration": 31,
          "name": "1",
          "unique_postings": 53979
        },
        {
          "median_posting_duration": 31,
          "name": "3",
          "unique_postings": 42213
        },
        {
          "median_posting_duration": 31,
          "name": "6",
          "unique_postings": 32078
        },
        {
          "median_posting_duration": 31,
          "name": "4",
          "unique_postings": 23835
        },
        {
          "median_posting_duration": 31,
          "name": "8",
          "unique_postings": 23529
        },
        {
          "median_posting_duration": 31,
          "name": "7",
          "unique_postings": 15945
        }
      ],
      "facet": "anz_sco_1",
      "limit": 10,
      "rank_by": "unique_postings"
    },
    "totals": {
      "median_posting_duration": 26,
      "unique_postings": 26412385
    }
  }
}

Retrieve Individual Job Postings

Analyzing labor market demand often requires access to the underlying posting records, not just aggregated summaries. Without a way to retrieve and filter individual job postings, it is difficult to review posting content, validate classification data, or build workflows that depend on the details of specific roles across global labor markets.

This API enables you to retrieve individual job posting records filtered by date range and activity status. It returns paginated results with selected fields such as job title, company name, city, posting and expiration dates, and relevance score, giving you direct access to the underlying posting data across global labor markets.

See the Global Postings API reference for full request parameters and response details.

When to Use

  • You want to retrieve and review individual job posting records across global labor markets
  • You need to access raw posting content to validate classification or enrichment data
  • You are building a workflow or application that depends on the details of specific job postings

Endpoint

https://api.lightcast.io/global-postings/postings

Sample Request

curl --request POST \
     --url https://api.lightcast.io/global-postings/postings \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXX' \
     --header 'content-type: application/json' \
     --data '
{
  "filter": {
    "when": {
      "start": "2019-01",
      "end": "2020-04",
      "type": "active"
    }
  },
  "fields": [
    "id",
    "posted",
    "expired",
    "body",
    "city_name",
    "company_name",
    "title_raw",
    "score"
  ],
  "order": [
    "score"
  ],
  "limit": 2
}
'

Sample Response

{
  "data": {
    "limit": 2,
    "page": 1,
    "pages_available": 5,
    "postings": [
      {
        "body": "<!--id: 2d84d38afa26df51799f1963125fa4-->Workplace Engineer (m/w/d)",
        "city_name": "[Unknown City], ",
        "company_name": "Tennet Tso Gmbh",
        "expired": null,
        "id": "2d84d38afa26df51799f1963125fa4",
        "posted": "2024-07-12",
        "score": 1,
        "title_raw": "Workplace Engineer (m/w/d)"
      },
      {
        "body": "<!--id: 466189d1440003b478a508a067a0e5-->Order to Invoice Specialist (OTI) with Polish & English (Warsaw)",
        "city_name": "Warsaw, Warszawa",
        "company_name": "Diebold Nixdorf",
        "expired": null,
        "id": "466189d1440003b478a508a067a0e5",
        "posted": "2024-07-30",
        "score": 1,
        "title_raw": "Order to Invoice Specialist (OTI) with Polish & English (Warsaw)"
      }
    ],
    "unique_postings": 6795,
    "viewable_postings": 6795
  }
}

Posting Distributions by Dimensions

Understanding how job postings are spread across experience requirements requires more than aggregate counts. Without a structured view of how postings are distributed across maximum years of experience thresholds, it is difficult to assess where employer demand is concentrated, identify experience gaps, or compare posting density across experience levels in global labor markets.

This API enables you to analyze how job postings are distributed across experience requirement ranges by returning data broken down into histogram buckets. Each bucket represents a percentile range and includes unique and duplicate posting counts, giving you a clear picture of where posting volume is concentrated across experience thresholds in global labor markets.

See the Global Postings Distributions API reference for full request parameters and response details.

When to Use

  • You want to understand how job postings are distributed across maximum years of experience requirements in global labor markets
  • You need to identify which experience thresholds have the highest or lowest posting density
  • You are analyzing employer demand patterns across experience levels for workforce planning or talent strategy

Endpoints

https://api.lightcast.io/global-postings/distributions/{distributionFacet}

Sample Request

curl --request POST \
     --url https://api.lightcast.io/global-postings/distributions/max_years_experience \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXX' \
     --header 'content-type: application/json' \
     --data '
{
  "distribution": {
    "type": "histogram"
  }
}
'

Sample Response

{
  "data": {
    "distribution": {
      "buckets": [
        {
          "duplicate_postings": 422706,
          "key": 25,
          "unique_postings": 126445,
          "value": 38178
        },
        {
          "duplicate_postings": 868120,
          "key": 50,
          "unique_postings": 257335,
          "value": 52000
        },
        {
          "duplicate_postings": 1231723,
          "key": 75,
          "unique_postings": 381181,
          "value": 90000
        }
      ],
      "domain": {
        "max": 500000,
        "min": 24980
      },
      "facet": "salary",
      "interval": null,
      "type": "percentile"
    },
    "totals": {
      "duplicate_postings": 3874932,
      "unique_postings": 1445428
    }
  }
}

Additional Resources

Updated 3 months ago

Did this page help you?

Updated 3 months ago

Did this page help you?