Dave Boyd
2b9d3e6d68
Includes: - API v1/v2 documentation, endpoints, request/response schemas - Complete survey catalog (60 surveys, live-fetched from API) - Series ID decode tables: LAUS, CES, SM, QCEW, OES, JOLTS, CPI, PPI - QCEW quarterly (47 fields) and annual (43 fields) CSV schemas - dc_md_va_unemployment.py: pulls 16 LAUS series for DC/MD/VA + DC MSA - Example API response and 5-year CSV output Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
297 lines
8.8 KiB
Markdown
297 lines
8.8 KiB
Markdown
# BLS Series ID Formats
|
||
|
||
Series IDs are the primary key for every BLS API call and bulk data file.
|
||
All IDs use a two-letter survey prefix followed by survey-specific coded segments.
|
||
|
||
---
|
||
|
||
## LAUS — Local Area Unemployment Statistics (prefix: LA)
|
||
|
||
**Series ID:** `LA[S][AAAAAAAAAAAAAAA][MM]`
|
||
|
||
| Pos | Length | Field | Notes |
|
||
|-----|--------|-------|-------|
|
||
| 1-2 | 2 | Prefix | Always `LA` |
|
||
| 3 | 1 | Seasonal adj | `S`=seasonally adjusted, `U`=unadjusted |
|
||
| 4-18 | 15 | Area code | See area type prefixes below |
|
||
| 19-20 | 2 | Measure code | See table below |
|
||
|
||
**Area code prefixes:**
|
||
| Prefix | Geography |
|
||
|--------|-----------|
|
||
| `ST` | State (2-digit FIPS + 12 zeros) |
|
||
| `MT` | Metropolitan statistical area |
|
||
| `MD` | Metro division |
|
||
| `CN` | County (5-digit FIPS + 10 zeros) |
|
||
| `CS` | City/sub-county |
|
||
| `RD` | Region/division |
|
||
|
||
**Measure codes:**
|
||
| Code | Measure |
|
||
|------|---------|
|
||
| 03 | Unemployment rate |
|
||
| 04 | Unemployment (level) |
|
||
| 05 | Employment |
|
||
| 06 | Labor force |
|
||
| 07 | Employment-population ratio |
|
||
| 08 | Labor force participation rate |
|
||
| 09 | Civilian noninstitutional population |
|
||
|
||
**Examples:**
|
||
```
|
||
LAUST110000000000003 → DC, state, seasonally adj, unemployment rate
|
||
LAUST110000000000005 → DC, state, seasonally adj, employment
|
||
LAUCN110010000000003 → DC County, unadjusted, unemployment rate
|
||
```
|
||
|
||
---
|
||
|
||
## CES — Current Employment Statistics, National (prefix: CE)
|
||
|
||
**Series ID:** `CE[S/U][IIIIIIII][DD]`
|
||
|
||
| Pos | Length | Field | Notes |
|
||
|-----|--------|-------|-------|
|
||
| 1-2 | 2 | Prefix | `CE` (national) or `SM` (state/metro) |
|
||
| 3 | 1 | Seasonal adj | `S`=seasonally adjusted, `U`=unadjusted |
|
||
| 4-11 | 8 | Industry code | Supersector (2) + NAICS-derived (6) |
|
||
| 12-13 | 2 | Data type | See table below |
|
||
|
||
**Industry code — supersector first 2 digits:**
|
||
| Code | Supersector |
|
||
|------|-------------|
|
||
| 00 | Total nonfarm |
|
||
| 05 | Total private |
|
||
| 06 | Goods-producing |
|
||
| 07 | Service-providing |
|
||
| 08 | Private service-providing |
|
||
| 09 | Government |
|
||
| 10 | Mining & logging |
|
||
| 20 | Construction |
|
||
| 30 | Manufacturing |
|
||
| 31 | Durable goods |
|
||
| 32 | Nondurable goods |
|
||
| 40 | Trade, transportation, utilities |
|
||
| 41 | Wholesale trade |
|
||
| 42 | Retail trade |
|
||
| 43 | Trans., warehousing, utilities |
|
||
| 50 | Information |
|
||
| 55 | Financial activities |
|
||
| 60 | Professional & business services |
|
||
| 65 | Education & health services |
|
||
| 70 | Leisure & hospitality |
|
||
| 80 | Other services |
|
||
| 90 | Government |
|
||
|
||
**Data type codes (most common):**
|
||
| Code | Measure |
|
||
|------|---------|
|
||
| 01 | All employees (thousands) |
|
||
| 02 | Average weekly hours, all employees |
|
||
| 03 | Average hourly earnings, all employees |
|
||
| 06 | Production/nonsupervisory employees |
|
||
| 07 | Avg weekly hours, prod/nonsupervisory |
|
||
| 08 | Avg hourly earnings, prod/nonsupervisory |
|
||
| 10 | Women employees |
|
||
| 11 | Avg weekly earnings, all employees |
|
||
|
||
**Examples:**
|
||
```
|
||
CES0000000001 → Total nonfarm, SA, all employees
|
||
CES0500000001 → Total private, SA, all employees
|
||
CES3000000001 → Manufacturing, SA, all employees
|
||
CES9000000001 → Government, SA, all employees
|
||
```
|
||
|
||
---
|
||
|
||
## SM — State & Metro Employment (CES State, prefix: SM)
|
||
|
||
**Series ID:** `SM[S/U][SS][MMMMM][IIIIIIII][DD]`
|
||
|
||
| Pos | Length | Field | Notes |
|
||
|-----|--------|-------|-------|
|
||
| 1-2 | 2 | Prefix | `SM` |
|
||
| 3 | 1 | Seasonal adj | `S` or `U` |
|
||
| 4-5 | 2 | State FIPS | e.g., `11`=DC, `24`=MD, `51`=VA |
|
||
| 6-10 | 5 | Area code | `00000`=statewide; MSA codes otherwise |
|
||
| 11-18 | 8 | Industry code | Same as CES above |
|
||
| 19-20 | 2 | Data type | Same as CES above |
|
||
|
||
**Examples:**
|
||
```
|
||
SMS110000000000001 → DC statewide, SA, all employees
|
||
SMS240000000000001 → Maryland statewide, SA, all employees
|
||
```
|
||
|
||
---
|
||
|
||
## QCEW — Quarterly Census of Employment & Wages (prefix: EN)
|
||
|
||
**Series ID:** `EN[U][AAAAA][D][Z][O][IIIIII]`
|
||
|
||
| Pos | Length | Field | Notes |
|
||
|-----|--------|-------|-------|
|
||
| 1-2 | 2 | Prefix | `EN` |
|
||
| 3 | 1 | Seasonal adj | Always `U` (unadjusted) |
|
||
| 4-8 | 5 | Area code | US=`00000`; state FIPS; county FIPS |
|
||
| 9 | 1 | Data type | `1`=qtrly; `2`=annual |
|
||
| 10 | 1 | Size code | `0`=all sizes; `1`–`9`=specific size classes |
|
||
| 11 | 1 | Ownership code | See table below |
|
||
| 12-17 | 6 | Industry code | NAICS or supersector |
|
||
|
||
**Ownership codes:**
|
||
| Code | Ownership |
|
||
|------|-----------|
|
||
| 0 | All ownerships |
|
||
| 1 | Federal government |
|
||
| 2 | State government |
|
||
| 3 | Local government |
|
||
| 4 | International government |
|
||
| 5 | Private |
|
||
|
||
**Examples:**
|
||
```
|
||
ENU1100010510000 → DC, quarterly, all sizes, private, total all industries
|
||
ENU0000010510000 → National, quarterly, private, all industries
|
||
```
|
||
|
||
---
|
||
|
||
## OES/OEWS — Occupational Employment & Wage Statistics (prefix: OE)
|
||
|
||
**Series ID:** `OE[U][T][AAAAAAA][IIIIII][OOOOOO][DD]`
|
||
|
||
| Pos | Length | Field | Notes |
|
||
|-----|--------|-------|-------|
|
||
| 1-2 | 2 | Prefix | `OE` |
|
||
| 3 | 1 | Seasonal adj | Always `U` |
|
||
| 4 | 1 | Area type | `N`=national; `S`=state; `M`=metro; `B`=metro div; `W`=nonmetro |
|
||
| 5-11 | 7 | Area code | BLS area code (not FIPS) |
|
||
| 12-17 | 6 | Industry code | NAICS or `000000` for cross-industry |
|
||
| 18-23 | 6 | Occupation code | SOC 6-digit code or `000000` for all |
|
||
| 24-25 | 2 | Data type | See table below |
|
||
|
||
**Data type codes:**
|
||
| Code | Measure |
|
||
|------|---------|
|
||
| 01 | Employment (thousands) |
|
||
| 02 | Employment % relative standard error |
|
||
| 03 | Hourly mean wage |
|
||
| 04 | Annual mean wage |
|
||
| 05 | Wage % relative standard error |
|
||
| 06 | Hourly 10th percentile wage |
|
||
| 07 | Hourly 25th percentile wage |
|
||
| 08 | Hourly median wage |
|
||
| 09 | Hourly 75th percentile wage |
|
||
| 10 | Hourly 90th percentile wage |
|
||
| 11 | Annual 10th percentile wage |
|
||
| 12 | Annual 25th percentile wage |
|
||
| 13 | Annual median wage |
|
||
| 14 | Annual 75th percentile wage |
|
||
| 15 | Annual 90th percentile wage |
|
||
|
||
**Examples:**
|
||
```
|
||
OEUM0000400000000000001 → National, all industries, all occupations, employment
|
||
OEUM0000400000015113201 → National, all industries, software devs, employment
|
||
```
|
||
|
||
---
|
||
|
||
## JOLTS — Job Openings & Labor Turnover (prefix: JT)
|
||
|
||
**Series ID:** `JT[S/U][IIIIII][E/J][RR][LL]`
|
||
|
||
| Pos | Length | Field | Notes |
|
||
|-----|--------|-------|-------|
|
||
| 1-2 | 2 | Prefix | `JT` |
|
||
| 3 | 1 | Seasonal adj | `S` or `U` |
|
||
| 4-9 | 6 | Industry code | NAICS supersector |
|
||
| 10 | 1 | Job status | `E`=total; `J`=job openings; `H`=hires; `L`=layoffs/discharges; `Q`=quits; `T`=total separations |
|
||
| 11-12 | 2 | Rate/level | `R`=rate; `L`=level (thousands) |
|
||
| 13-14 | 2 | Ownership | `00`=total; `10`=private; `20`=government |
|
||
|
||
**Examples:**
|
||
```
|
||
JTS000000000000JOL → Total nonfarm, job openings, level
|
||
JTS000000000000JOR → Total nonfarm, job openings, rate
|
||
JTS000000000000HIL → Total nonfarm, hires, level
|
||
JTS000000000000TSL → Total nonfarm, total separations, level
|
||
```
|
||
|
||
---
|
||
|
||
## CPI — Consumer Price Index (prefix: CU / CW / SU)
|
||
|
||
**Prefixes:**
|
||
- `CU` — CPI-U (All Urban Consumers)
|
||
- `CW` — CPI-W (Urban Wage Earners)
|
||
- `SU` — Chained CPI-U (C-CPI-U)
|
||
|
||
**Series ID:** `CU[S/U][R/S][AAAA][IIIIII]`
|
||
|
||
| Pos | Length | Field | Notes |
|
||
|-----|--------|-------|-------|
|
||
| 1-2 | 2 | Prefix | `CU`, `CW`, or `SU` |
|
||
| 3 | 1 | Seasonal adj | `S`=SA; `U`=unadjusted |
|
||
| 4 | 1 | Periodicity | `R`=monthly; `S`=semiannual |
|
||
| 5-8 | 4 | Area code | `0000`=US city average; others=specific metros |
|
||
| 9-14 | 6 | Item code | Expenditure category code |
|
||
|
||
**Common item codes:**
|
||
| Code | Category |
|
||
|------|----------|
|
||
| SA0 | All items |
|
||
| SA0E | Energy |
|
||
| SA0L1E | All items less food and energy (core) |
|
||
| SAF | Food |
|
||
| SAF1 | Food at home |
|
||
| SAF11 | Cereals and bakery products |
|
||
| SAH | Housing |
|
||
| SAH1 | Shelter |
|
||
| SAT | Transportation |
|
||
| SAM | Medical care |
|
||
|
||
**Examples:**
|
||
```
|
||
CUUR0000SA0 → US city avg, unadjusted, all items
|
||
CUSR0000SA0L1E → US city avg, SA, core (ex food & energy)
|
||
CUUR0000SAF → US city avg, unadjusted, food
|
||
```
|
||
|
||
---
|
||
|
||
## PPI — Producer Price Index (prefix: WP / PC)
|
||
|
||
- `WP` — PPI commodities (older series)
|
||
- `PC` — PPI industry data (NAICS-based, current)
|
||
|
||
**Series ID (PC):** `PC[U][IIIIII][IIIIII]`
|
||
|
||
| Pos | Length | Field | Notes |
|
||
|-----|--------|-------|-------|
|
||
| 1-2 | 2 | Prefix | `PC` |
|
||
| 3 | 1 | Seasonal adj | `U`=unadjusted (most PPI); `S`=SA |
|
||
| 4-9 | 6 | Industry code | NAICS 6-digit |
|
||
| 10-15 | 6 | Product code | Product within the industry |
|
||
|
||
---
|
||
|
||
## Helpful Discovery Commands
|
||
|
||
```bash
|
||
# All surveys
|
||
curl -s "https://api.bls.gov/publicAPI/v2/surveys" | python3 -m json.tool
|
||
|
||
# Popular series for a survey
|
||
curl -s "https://api.bls.gov/publicAPI/v2/timeseries/popular?survey=LA"
|
||
|
||
# Bulk download decode tables (e.g. LAUS area codes)
|
||
curl -s "https://download.bls.gov/pub/time.series/la/la.area" | head -50
|
||
curl -s "https://download.bls.gov/pub/time.series/la/la.measure"
|
||
curl -s "https://download.bls.gov/pub/time.series/ce/ce.datatype"
|
||
curl -s "https://download.bls.gov/pub/time.series/ce/ce.supersector"
|
||
curl -s "https://download.bls.gov/pub/time.series/sm/sm.state"
|
||
```
|