Register for a free BLS API v2 key at https://data.bls.gov/registrationEngine/ to access the registered tier (500 queries/day, 50 series per query, 20 years per query)
Construct the OEWS series ID: series IDs follow the pattern OEWSXXXXXXXXXXXXXXXX where positions encode area type, area code, industry, occupation SOC code, and datatype; use the BLS OEWS series ID builder at bls.gov or refer to the OEWS technical notes
Fetch observations via POST https://api.bls.gov/publicAPI/v2/timeseries/data/ with a JSON body containing seriesid (array of up to 50), startyear, endyear, and registrationkey
Parse the value field in each data point (mean annual wage, hourly wage, employment count depending on datatype suffix) and the footnote_codes for suppressed or estimated values
For national estimates by occupation, use the national cross-industry series (area code 0000000, industry 000000) to get median and mean wages for any SOC code
Compare geographic areas by requesting series for multiple MSA area codes (area type = 4) in the same batch POST call to stay within the 50-series-per-query limit
Known gotchas
OEWS data is published once per year (typically in May) reflecting the prior year's survey; the BLS API returns annual data points — it is not a real-time or monthly wage feed
Many detailed SOC codes and small geographic areas have suppressed wage data (footnote code H) because the sample is too small for disclosure; build fallback logic to use broader geographic or occupational groupings
OEWS series IDs are long (20 characters) and encode many fields positionally; a single transposition error silently returns a 'Series not found' error — validate IDs against the BLS OEWS area and occupation code reference files before querying
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp