bls-data/README.md

BLS Data Reference

Bureau of Labor Statistics — API access, dataset catalog, series ID formats, and field schemas.

Quick Start

1. Register for an API key: https://data.bls.gov/registrationEngine/
2. Base API endpoint: https://api.bls.gov/publicAPI/v2/timeseries/data/
3. Content-Type: application/json (POST)

---

API Versions

Feature	v1 (no key)	v2 (registered)
Daily query limit	25	500
Series per query	25	50
Years of history	10	20
Net/percent changes	No	Yes
Series descriptions	No	Yes
Calculations	No	Yes

---

Registration

• URL: https://data.bls.gov/registrationEngine/
• Free, no approval needed — instant key via email
• Key goes in the JSON payload as "registrationkey": "YOUR_KEY"

---

Endpoints

GET: Survey List

GET https://api.bls.gov/publicAPI/v2/surveys
GET https://api.bls.gov/publicAPI/v2/surveys/{survey_abbreviation}

Returns all survey codes and names. See surveys.json for full list.

GET: Popular Series

GET https://api.bls.gov/publicAPI/v2/timeseries/popular
GET https://api.bls.gov/publicAPI/v2/timeseries/popular?survey={abbreviation}

Returns the 25 most-requested series IDs for a survey.

POST: Time Series Data

POST https://api.bls.gov/publicAPI/v2/timeseries/data/
Content-Type: application/json

Minimal request (unregistered):

{
  "seriesid": ["LAUST110000000000003", "CES0000000001"],
  "startyear": "2023",
  "endyear": "2025"
}

Full request (registered, v2 features):

{
  "seriesid": ["LAUST110000000000003", "CES0000000001"],
  "startyear": "2020",
  "endyear": "2025",
  "registrationkey": "YOUR_KEY",
  "catalog": true,
  "calculations": true,
  "annualaverage": true,
  "aspects": true
}

Response schema:

{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 114,
  "message": [],
  "Results": {
    "series": [
      {
        "seriesID": "LAUST110000000000003",
        "catalog": {
          "series_title": "...",
          "survey_name": "...",
          "measure_data_type": "..."
        },
        "data": [
          {
            "year": "2025",
            "period": "M12",
            "periodName": "December",
            "value": "6.4",
            "footnotes": [
              { "code": "R", "text": "Data were subject to revision on April 8, 2026." }
            ],
            "calculations": {
              "net_changes": { "1": "0.1", "3": "-0.2", "6": "0.5", "12": "-0.3" },
              "pct_changes": { "1": "1.6", "3": "-3.0", "6": "8.3", "12": "-4.5" }
            }
          }
        ]
      }
    ]
  }
}

Period codes:

• Monthly: M01–M12, M13 (annual average)
• Quarterly: Q01–Q04, Q05 (annual average)
• Annual: A01

Status codes: REQUEST_SUCCEEDED, REQUEST_FAILED, REQUEST_NOT_PROCESSED

Error footnote codes:

• R — Revised
• P — Preliminary
• X — Data unavailable (e.g., government shutdown gap)
• N — Not available

---

Python Example

import requests

API_KEY = "YOUR_KEY"
BASE_URL = "https://api.bls.gov/publicAPI/v2/timeseries/data/"

def get_series(series_ids, start_year, end_year):
    payload = {
        "seriesid": series_ids,
        "startyear": str(start_year),
        "endyear": str(end_year),
        "registrationkey": API_KEY,
        "catalog": True,
        "calculations": True,
        "annualaverage": True,
    }
    r = requests.post(BASE_URL, json=payload)
    r.raise_for_status()
    data = r.json()
    if data["status"] != "REQUEST_SUCCEEDED":
        raise ValueError(f"BLS API error: {data['message']}")
    return data["Results"]["series"]

# DC unemployment rate (LAUS)
series = get_series(["LAUST110000000000003"], 2020, 2025)
for obs in series[0]["data"]:
    print(obs["year"], obs["periodName"], obs["value"])

---

Bulk Download (flat files)

Base URL: https://download.bls.gov/pub/time.series/

Each survey folder contains:

• {prefix}.series — master list of all series IDs with metadata
• {prefix}.data.{N}.{name} — actual observations, split by category
• {prefix}.{dimension} — lookup/decode tables (area, industry, measure, etc.)

Key folder prefixes:

la/   — LAUS (local area unemployment)
ce/   — CES national employment
sm/   — State & Metro employment (CES state)
en/   — QCEW
oe/   — OES (occupational employment)
jt/   — JOLTS
cu/   — CPI-U
wp/   — PPI commodities

Files are tab-delimited. Useful for bulk PostgreSQL ingest.

---

Files in this folder

• README.md — this file
• surveys.json — complete survey list from the API
• series_id_formats.md — series ID decode tables for each key dataset
• qcew_field_schema.md — QCEW quarterly and annual CSV field layouts
• api_response_example.json — real API response sample