bls_oews_wages
Retrieve BLS OEWS occupational wage and employment benchmarks for specific occupations, areas, and measures. Builds validated series IDs and batches them into one request, no API key needed.
Instructions
BLS OEWS occupational wage/employment benchmarking by area × occupation × datatype (keyless; api.bls.gov). Builds validated 25-char series IDs from structured inputs and batches them into one POST — NO year input (OEWS serves only the latest annual release). Inputs: occupation (curated enum, e.g. 'software_developer') or soc (raw 6-digit SOC, ^[0-9]{6}$ NO hyphen — at least ONE required); area (default 'national', 2-letter USPS state, or 5-digit CBSA metro code); datatype (default 'annual_mean'; annual_mean/annual_median/hourly_mean/hourly_median/employment). Returns { results:[{ area:{type,code,label}, occupation:{soc,key,label}, measure:{key,code,units}, value:number|null, valueUnavailable:bool, referenceYear, referencePeriod, footnotes, seriesId }] } + honest _meta. ★H1: OEWS is an ANNUAL point-in-time snapshot (reference May ); BLS API serves ONLY the most recent release, may lag ~1 year. NOT monthly/current-quarter. ★H2: a built-ID with no published value (occupation not surveyed or suppressed in that area) → value:null (NOT a tool error). ★H3: measure.units is set from datatype — annual_mean/annual_median=dollars/year; hourly_mean/hourly_median=dollars/hour; employment=count. NEVER mislabeled. ★H4: the API returns real numerics (no '#' top-code). area×occupation×datatype is capped at the tier's series cap (v1 25 / v2 50) and refused over-cap with the count named — never silently truncated; REQUEST_NOT_PROCESSED → rate_limited THROWS. Active tier (v1 keyless ~25/day or v2 BLS_API_KEY ~500/day) and series-cap limits disclosed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| soc | No | One or more RAW 6-digit SOC codes (the long-tail passthrough) — HYPHENLESS (use 151252, not 15-1252; the hyphen is rejected). A raw soc that matches a curated occupation is auto-labeled; otherwise key/label are null. At least one of occupation/soc is required. | |
| area | No | One or more geographies (default ["national"]). Each element is "national", a 2-letter USPS state code (e.g. CA, TX, DC — the curated state enum), OR a 5-digit CBSA metropolitan code (^\d{5}$, e.g. 19100 for Dallas-Fort Worth). Resolved internally to the OEWS areatype + zero-padded area code; an unknown token is rejected (invalid_input, never a malformed series ID on the wire). | |
| datatype | No | One or more measures (default ["annual_mean"]): annual_mean (dollars/year), annual_median (dollars/year), hourly_mean (dollars/hour), hourly_median (dollars/hour), employment (count jobs). Each row carries measure.units from this map (H3 — never mislabel). | |
| occupation | No | One or more CURATED occupation enum keys (typo-proof; each carries an SOC + official label): all_occupations, software_developer (15-1252), computer_systems_analyst, info_security_analyst, management_analyst, project_mgmt_specialist, logistician, accountant_auditor, general_ops_manager, civil_engineer, electrical_engineer, mechanical_engineer, industrial_engineer, lawyer, technical_writer, admin_assistant. The ~830-SOC long tail is reachable via `soc`. At least one of occupation/soc is required. |