Skip to content
Thesma docs

US BLS

Five Bureau of Labor Statistics surveys, exposed as standalone endpoints and as ?include=labor_context enrichment on SEC filings. The US BLS dataset is what makes cross-dataset queries (“what’s Apple’s headcount trend vs. their industry?”) a single API call instead of three.

Coverage

Section titled “Coverage”
SurveyFrequencyGeoWhat it measures
CES (Current Employment Statistics)MonthlyNational industryEmployment, average hourly earnings, hours worked by NAICS. Seasonally adjusted.
QCEW (Quarterly Census of Employment and Wages)QuarterlyCounty × NAICSEmployment counts and wage totals by county and industry.
OEWS (Occupational Employment and Wage Statistics)AnnualNational + metroEmployment and wages by SOC occupation code.
JOLTS (Job Openings and Labor Turnover Survey)MonthlyIndustry + state + regionJob openings, hires, quits, layoffs.
LAUS (Local Area Unemployment Statistics)MonthlyState + countyUnemployment rate, labor force participation.

Known limitations

Section titled “Known limitations”
  • CPI, PPI, ECI, productivity, and NCS are not yet covered. On the post-1.0.0 roadmap. If any of these are load-bearing for your use case, let us know at hello@thesma.dev — it informs prioritisation.
  • Seasonal adjustment is survey-specific. CES values are seasonally adjusted by default; QCEW is not (BLS doesn’t publish seasonally-adjusted QCEW). Check the adjustment field on each response.
  • County-level wage data has disclosure suppression. QCEW suppresses values for very small industry-in-county cells to protect employer confidentiality. Expect occasional null fields at the county × NAICS intersection for thinly populated industries.

Endpoints

Section titled “Endpoints”

Industries (CES + employment trends)

Section titled “Industries (CES + employment trends)”
MethodPathPurpose
GET/v1/us/bls/industriesList industries (NAICS) with BLS coverage.
GET/v1/us/bls/industries/{naics}Industry detail.
GET/v1/us/bls/industries/{naics}/employmentMonthly employment time series (CES).
GET/v1/us/bls/industries/{naics}/employment/latestMost recent month snapshot.

Counties (QCEW + LAUS)

Section titled “Counties (QCEW + LAUS)”
MethodPathPurpose
GET/v1/us/bls/counties/{fips}/employmentCounty employment by industry (QCEW).
GET/v1/us/bls/counties/{fips}/wagesCounty wage totals by industry (QCEW).
GET/v1/us/bls/counties/{fips}/unemploymentCounty unemployment rate (LAUS).
GET/v1/us/bls/counties/compareMulti-county comparison on a single metric.

States (LAUS)

Section titled “States (LAUS)”
MethodPathPurpose
GET/v1/us/bls/states/{fips}/unemploymentState unemployment rate and labor force (LAUS).
GET/v1/us/bls/states/compareMulti-state comparison.
GET/v1/us/bls/states/{fips}/turnoverState-level JOLTS (openings, hires, quits, layoffs).

Occupations (OEWS)

Section titled “Occupations (OEWS)”
MethodPathPurpose
GET/v1/us/bls/occupationsList SOC occupations.
GET/v1/us/bls/occupations/{soc}Occupation detail.
GET/v1/us/bls/occupations/{soc}/wagesWage distribution (mean, 10th / 25th / 50th / 75th / 90th percentiles).

Turnover (JOLTS)

Section titled “Turnover (JOLTS)”
MethodPathPurpose
GET/v1/us/bls/industries/{naics}/turnoverIndustry-level openings, hires, quits, layoffs.
GET/v1/us/bls/industries/{naics}/turnover/latestMost recent month snapshot.
GET/v1/us/bls/regions/{region}/turnoverRegional JOLTS (Northeast, South, Midwest, West).
GET/v1/us/bls/turnover/by-sizeJOLTS by establishment size.

Metrics catalogue

Section titled “Metrics catalogue”
MethodPathPurpose
GET/v1/us/bls/metricsAll BLS metrics across surveys with their dimensions.
GET/v1/us/bls/metrics/{metric}Metric detail — source, unit, cadence, geographic level.

Cross-dataset enrichment on SEC

Section titled “Cross-dataset enrichment on SEC”

The ?include=labor_context parameter on any SEC company or financials endpoint adds a labor_context object with BLS data for the company’s NAICS industry:

{
  "labor_context": {
    "naics": "3254",
    "naics_title": "Pharmaceutical and Medicine Manufacturing",
    "industry_employment": 177200,
    "industry_employment_yoy": -0.018,
    "industry_avg_hourly_earnings": 44.87,
    "industry_earnings_yoy": 0.041,
    "period": "2025-11",
    "source": "BLS CES"
  }
}

See the cross-dataset labor-context recipe for the full walk-through.

Screener filters

Section titled “Screener filters”

The /v1/us/sec/screener endpoint supports BLS-side filters for finding companies whose industry labor conditions meet a threshold:

  • industry_employment_yoy_min / _max
  • industry_earnings_yoy_min / _max
  • industry_openings_rate_min
  • state_unemployment_rate_max
  • county_unemployment_rate_max (uses the company’s HQ county)

Example: 5-year employment trend for pharmaceuticals (NAICS 3254)

Section titled “Example: 5-year employment trend for pharmaceuticals (NAICS 3254)”
Terminal window
curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/bls/industries/3254/employment?from_date=2020-01&to_date=2025-12" \
  | jq '.data[] | {period, employment, avg_hourly_earnings}'

See the BLS industry-trend recipe for the full example with Python SDK and expected response shape.

See also

Section titled “See also”