249 lines
9.4 KiB
Markdown
249 lines
9.4 KiB
Markdown
---
|
|
title: "Bureau of Labor Statistics (BLS) Public Data API"
|
|
task: ""
|
|
lineage_type: import
|
|
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/database-lookup/references/bls.md
|
|
upstream_sha: 9c9bd2e9
|
|
imported_at: 2026-06-26
|
|
prompt_class: prompt
|
|
upstream_changes: accepted
|
|
author: upstream
|
|
validated: 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:**
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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.
|