drug-discovery-prompts/upstream/K-Dense-AI-scientific-agent-skills/skills/database-lookup/references/bls.md

title, task, lineage_type, upstream_source, upstream_sha, imported_at, prompt_class, upstream_changes, author, validated

title	task	lineage_type	upstream_source	upstream_sha	imported_at	prompt_class	upstream_changes	author	validated
Bureau of Labor Statistics (BLS) Public Data API		import	https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/database-lookup/references/bls.md	9c9bd2e9	2026-06-26	prompt	accepted	upstream	false

Bureau of Labor Statistics (BLS) Public Data API

Base URL

https://api.bls.gov/publicAPI/v2

Version 1 (no key): https://api.bls.gov/publicAPI/v1

Authentication

API key optional but strongly recommended. Register at https://data.bls.gov/registrationEngine/

• V1 (no key): Limited to 25 requests/day, 10-year date range, 25 series per query.
• V2 (with key): 500 requests/day, 20-year date range, 50 series per query, plus catalog data and calculations.

Key Endpoints

1. Get Series Data (POST -- primary method)

POST /timeseries/data/

Content-Type: application/json

Request body:

{
  "seriesid": ["CUUR0000SA0", "LNS14000000"],
  "startyear": "2020",
  "endyear": "2024",
  "registrationkey": "YOUR_KEY",
  "catalog": true,
  "calculations": true,
  "annualaverage": true,
  "aspects": true
}

Field	Required	V1	V2	Description
seriesid	Yes	Yes	Yes	Array of series IDs (max 25 v1 / 50 v2)
startyear	Yes	Yes	Yes	4-digit start year
endyear	Yes	Yes	Yes	4-digit end year
registrationkey	No	No	Yes	API key (required for v2 features)
catalog	No	No	Yes	true to include series metadata
calculations	No	No	Yes	true to include net/pct changes
annualaverage	No	No	Yes	true to include annual averages
aspects	No	No	Yes	true to include footnotes and aspects

2. Get Single Series Data (GET -- convenience)

GET /timeseries/data/{seriesID}

Example:

https://api.bls.gov/publicAPI/v2/timeseries/data/CUUR0000SA0?registrationkey=YOUR_KEY&startyear=2022&endyear=2024

3. Latest Data (GET -- no date range)

GET /timeseries/data/{seriesID}

Without startyear/endyear, returns the most recent 3 years.

Example:

https://api.bls.gov/publicAPI/v2/timeseries/data/LNS14000000?registrationkey=YOUR_KEY

Common Series IDs

Consumer Price Index (CPI)

Series ID	Description
CUUR0000SA0	CPI-U All Items, US City Avg, Not Seasonally Adj
CUSR0000SA0	CPI-U All Items, US City Avg, Seasonally Adj
CUUR0000SAF1	CPI-U Food, US City Avg
CUUR0000SETB01	CPI-U Gasoline (all types)
CUUR0000SAH1	CPI-U Shelter
CUUR0000SAM	CPI-U Medical Care

CPI series ID structure: CU + U/S (unadj/adj) + R/S (revision) + area code + item code

Employment / Unemployment (Current Population Survey)

Series ID	Description
LNS14000000	Unemployment Rate (seasonally adjusted)
LNS11000000	Civilian Labor Force Level
LNS12000000	Employment Level
LNS13000000	Unemployment Level
LNS14000006	Unemployment Rate - Black or African American
LNS14000009	Unemployment Rate - Hispanic or Latino

Employment (Current Employment Statistics / Nonfarm Payrolls)

Series ID	Description
CES0000000001	Total Nonfarm Employment (seasonally adj)
CES0500000003	Average Hourly Earnings, Total Private
CES0500000002	Average Weekly Hours, Total Private

Producer Price Index (PPI)

Series ID	Description
WPSFD4	PPI Final Demand
WPUFD49104	PPI Final Demand less Foods & Energy

Employment Cost Index (ECI)

Series ID	Description
CIU1010000000000A	ECI Total Compensation, All Civilians

Occupational Employment & Wage Statistics (OEWS)

Series ID Pattern	Description
OEUM003342000000011-0000	Example: specific occupation/area combo

OEWS series IDs are complex. Use the BLS Series ID finder: https://data.bls.gov/cgi-bin/srgate

Series ID Structure

BLS series IDs encode survey, seasonal adjustment, area, industry, and item information. Key survey prefixes:

Prefix	Survey
CU	Consumer Price Index
LN	Current Population Survey (Labor Force)
CE	Current Employment Statistics
WP	Producer Price Index
EI	Employment Cost Index / National Compensation
OE	Occupational Employment & Wage Statistics
LA	Local Area Unemployment Statistics
SM	State and Metro Area Employment (CES)
JT	Job Openings and Labor Turnover (JOLTS)

Response Format

Standard response

{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 85,
  "message": [],
  "Results": {
    "series": [
      {
        "seriesID": "CUUR0000SA0",
        "catalog": {
          "series_title": "All items in U.S. city average, all urban consumers, not seasonally adjusted",
          "series_id": "CUUR0000SA0",
          "seasonality": "Not Seasonally Adjusted",
          "survey_name": "Consumer Price Index - All Urban Consumers",
          "survey_abbreviation": "CU",
          "measure_data_type": "All items",
          "area": "U.S. city average",
          "item": "All items"
        },
        "data": [
          {
            "year": "2024",
            "period": "M01",
            "periodName": "January",
            "latest": "true",
            "value": "308.417",
            "footnotes": [{}],
            "calculations": {
              "net_changes": {
                "1": "0.5",
                "3": "1.2",
                "6": "2.1",
                "12": "3.1"
              },
              "pct_changes": {
                "1": "0.2",
                "3": "0.4",
                "6": "0.7",
                "12": "3.1"
              }
            }
          },
          {
            "year": "2023",
            "period": "M12",
            "periodName": "December",
            "value": "306.746",
            "footnotes": [{}]
          }
        ]
      }
    ]
  }
}

Key fields in data objects

• year: 4-digit year string
• period: M01-M12 (monthly), Q01-Q05 (quarterly), A01 (annual), S01-S03 (semi-annual)
• periodName: Human-readable period name
• value: String (convert to float for calculations)
• latest: "true" on the most recent observation only
• calculations: Only present when calculations: true in request (V2). Contains net_changes and pct_changes over 1, 3, 6, 12 month spans.
• footnotes: Array of footnote objects

Error response

{
  "status": "REQUEST_NOT_PROCESSED",
  "responseTime": 10,
  "message": ["No data available for the given series and date range."],
  "Results": {
    "series": []
  }
}

Rate Limits

Feature	V1 (no key)	V2 (with key)
Daily query limit	25 requests	500 requests
Series per query	25	50
Years per query	10	20
Catalog data	No	Yes
Calculations	No	Yes
Annual averages	No	Yes
Net/pct changes	No	Yes

Notes

• BLS strongly prefers POST requests for data retrieval. The GET endpoint is a convenience wrapper.
• Period M13 represents the annual average (only present when annualaverage: true).
• All value fields are strings. Missing data is typically omitted (the observation simply won't appear).
• For CPI percent change (inflation rate), you can either calculate from raw index values or use the V2 calculations feature which provides pre-computed 12-month percent changes.
• The BLS website has a Series ID finder tool for constructing IDs: https://data.bls.gov/cgi-bin/srgate
• Bulk data is available for download at https://download.bls.gov/pub/time.series/ organized by survey prefix.