Retrieve single or multiple time series data
openapi: 3.0.3
info:
title: BLS Public Data Surveys Time Series API
description: 'The Bureau of Labor Statistics (BLS) Public Data API provides programmatic access to the full catalog of official federal labor and economic statistics published by the U.S. Department of Labor. The API delivers historical time-series data spanning employment, unemployment rates, Consumer Price Index (CPI), Producer Price Index (PPI), wages and earnings, and productivity metrics drawn from major BLS surveys.
Two versions are available: Version 1.0 (unauthenticated, up to 25 series per request, 10 years of data per query) and Version 2.0 (requires free registration, up to 50 series per request, 20 years of data, adds catalog metadata, net/percent change calculations, and optional annual averages). Responses are served in JSON format via HTTPS POST requests.'
version: '2.0'
contact:
name: Bureau of Labor Statistics
url: https://www.bls.gov/developers/home.htm
license:
name: Public Domain (U.S. Government Work)
url: https://www.usa.gov/government-works
servers:
- url: https://api.bls.gov/publicAPI/v2
description: BLS Public Data API Version 2.0 (registration required)
- url: https://api.bls.gov/publicAPI/v1
description: BLS Public Data API Version 1.0 (no registration required)
tags:
- name: Time Series
description: Retrieve single or multiple time series data
paths:
/timeseries/data/:
post:
operationId: getMultipleTimeSeries
summary: Retrieve multiple time series data
description: Retrieve data for one or more BLS time series identifiers. Version 2.0 supports up to 50 series per request and up to 20 years of data, and optionally returns catalog metadata, net change, percent change, and annual averages. Version 1.0 supports up to 25 series and 10 years of data without an API key.
tags:
- Time Series
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimeSeriesRequest'
examples:
single_series_v1:
summary: Single series request (v1, no key)
value:
seriesid:
- LNS14000000
startyear: '2020'
endyear: '2023'
multi_series_v2:
summary: Multiple series with v2 options
value:
seriesid:
- LNS14000000
- CES0000000001
startyear: '2020'
endyear: '2023'
registrationkey: YOUR_REGISTRATION_KEY
catalog: true
calculations: true
annualaverage: true
responses:
'200':
description: Successful response with time series data
content:
application/json:
schema:
$ref: '#/components/schemas/TimeSeriesResponse'
examples:
success:
summary: Successful data response
value:
status: REQUEST_SUCCEEDED
responseTime: 120
message: []
Results:
series:
- seriesID: LNS14000000
catalog:
series_title: Unemployment Rate
series_id: LNS14000000
seasonality: Seasonally Adjusted
survey_name: Labor Force Statistics including the National Unemployment Rate
survey_abbreviation: LN
measure_data_type: Percent
commerce_industry: null
occupation: null
cps_labor_force_status: Unemployment rate
demographic_race: All Races
demographic_gender: Both Sexes
demographic_origin: All Origins
demographic_age: 16 years and over
demographic_education: null
area: United States
data:
- year: '2023'
period: M12
periodName: December
latest: 'true'
value: '3.7'
footnotes:
- code: ''
text: ''
'400':
description: Bad request - invalid parameters or series IDs
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/timeseries/data/{series_id}:
get:
operationId: getSingleTimeSeries
summary: Retrieve a single time series by series ID
description: Retrieve data for a single BLS time series using an HTTP GET request. Series ID must be a valid BLS series identifier. Optional query parameters allow filtering by year range.
tags:
- Time Series
parameters:
- name: series_id
in: path
required: true
description: A valid BLS series identifier (e.g., LNS14000000 for national unemployment rate, CES0000000001 for total nonfarm employment).
schema:
type: string
example: LNS14000000
- name: startyear
in: query
required: false
description: The first year of data to return (four-digit year). If omitted, returns the most recent three years.
schema:
type: string
pattern: ^\d{4}$
example: '2020'
- name: endyear
in: query
required: false
description: The last year of data to return (four-digit year). If omitted, returns the current year.
schema:
type: string
pattern: ^\d{4}$
example: '2023'
- name: registrationkey
in: query
required: false
description: BLS API registration key obtained via free registration at https://data.bls.gov/registrationEngine/. Required for v2 features and higher rate limits.
schema:
type: string
responses:
'200':
description: Successful response with time series data
content:
application/json:
schema:
$ref: '#/components/schemas/TimeSeriesResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/timeseries/popular:
get:
operationId: getPopularTimeSeries
summary: Retrieve popular/featured time series
description: Returns a list of commonly requested BLS time series identifiers.
tags:
- Time Series
parameters:
- name: survey
in: query
required: false
description: Filter popular series by survey abbreviation (e.g., CE, CU, LA).
schema:
type: string
- name: registrationkey
in: query
required: false
description: BLS API registration key.
schema:
type: string
responses:
'200':
description: List of popular time series
content:
application/json:
schema:
$ref: '#/components/schemas/PopularSeriesResponse'
components:
schemas:
DataPoint:
type: object
properties:
year:
type: string
description: Four-digit year of the observation.
example: '2023'
period:
type: string
description: Period code. Monthly values are M01-M12; quarterly values are Q01-Q04; annual values are A01.
example: M12
periodName:
type: string
description: Human-readable period name.
example: December
latest:
type: string
enum:
- 'true'
- 'false'
description: Indicates whether this is the most recent data point.
example: 'true'
value:
type: string
description: The statistical value for the period (as a string to preserve precision).
example: '3.7'
footnotes:
type: array
items:
$ref: '#/components/schemas/Footnote'
calculations:
$ref: '#/components/schemas/DataPointCalculations'
DataPointCalculations:
type: object
description: Calculations for a specific data point.
properties:
net_changes:
type: object
additionalProperties:
type: string
pct_changes:
type: object
additionalProperties:
type: string
SeriesResult:
type: object
properties:
seriesID:
type: string
description: The BLS series identifier.
example: LNS14000000
catalog:
$ref: '#/components/schemas/SeriesCatalog'
data:
type: array
items:
$ref: '#/components/schemas/DataPoint'
calculations:
$ref: '#/components/schemas/Calculations'
TimeSeriesRequest:
type: object
required:
- seriesid
properties:
seriesid:
type: array
items:
type: string
minItems: 1
maxItems: 50
description: Array of BLS series identifiers. Version 1.0 supports up to 25 series; Version 2.0 supports up to 50 series per request.
example:
- LNS14000000
- CES0000000001
startyear:
type: string
pattern: ^\d{4}$
description: First year of data to retrieve. Version 1.0 allows up to 10 years of data; Version 2.0 allows up to 20 years.
example: '2020'
endyear:
type: string
pattern: ^\d{4}$
description: Last year of data to retrieve.
example: '2023'
registrationkey:
type: string
description: BLS API registration key for Version 2.0 access. Obtain via free registration at https://data.bls.gov/registrationEngine/.
catalog:
type: boolean
default: false
description: If true, returns catalog metadata for each series (v2 only). Includes series title, survey name, seasonality, measure type, and demographic filters.
calculations:
type: boolean
default: false
description: If true, returns net change and percent change calculations for each data point (v2 only).
annualaverage:
type: boolean
default: false
description: If true, includes annual average values where available (v2 only).
aspects:
type: boolean
default: false
description: If true, returns aspect data associated with the series where applicable (v2 only).
Footnote:
type: object
properties:
code:
type: string
description: Footnote code (e.g., P for preliminary, R for revised).
example: P
text:
type: string
description: Full text of the footnote.
example: Preliminary
SeriesCatalog:
type: object
description: Catalog metadata for a BLS series (returned when catalog=true, v2 only).
properties:
series_title:
type: string
example: Unemployment Rate
series_id:
type: string
example: LNS14000000
seasonality:
type: string
enum:
- Seasonally Adjusted
- Not Seasonally Adjusted
example: Seasonally Adjusted
survey_name:
type: string
example: Labor Force Statistics including the National Unemployment Rate
survey_abbreviation:
type: string
example: LN
measure_data_type:
type: string
example: Percent
commerce_industry:
type: string
nullable: true
occupation:
type: string
nullable: true
cps_labor_force_status:
type: string
nullable: true
example: Unemployment rate
demographic_race:
type: string
nullable: true
example: All Races
demographic_gender:
type: string
nullable: true
example: Both Sexes
demographic_origin:
type: string
nullable: true
example: All Origins
demographic_age:
type: string
nullable: true
example: 16 years and over
demographic_education:
type: string
nullable: true
area:
type: string
nullable: true
example: United States
ErrorResponse:
type: object
properties:
status:
type: string
enum:
- REQUEST_FAILED_ERROR
- REQUEST_NOT_PROCESSED
example: REQUEST_FAILED_ERROR
responseTime:
type: integer
message:
type: array
items:
type: string
description: Array of error messages describing what went wrong.
example:
- Series INVALID_ID does not exist
Results:
type: object
nullable: true
TimeSeriesResponse:
type: object
properties:
status:
type: string
enum:
- REQUEST_SUCCEEDED
- REQUEST_FAILED_ERROR
- REQUEST_NOT_PROCESSED
description: Overall status of the API request.
example: REQUEST_SUCCEEDED
responseTime:
type: integer
description: Server response time in milliseconds.
example: 120
message:
type: array
items:
type: string
description: Array of informational or error messages. Empty array on full success.
Results:
type: object
properties:
series:
type: array
items:
$ref: '#/components/schemas/SeriesResult'
PopularSeriesResponse:
type: object
properties:
status:
type: string
example: REQUEST_SUCCEEDED
responseTime:
type: integer
message:
type: array
items:
type: string
Results:
type: object
properties:
series:
type: array
items:
type: object
properties:
seriesID:
type: string
seriesTitle:
type: string
Calculations:
type: object
description: Net and percent change calculations for the series (v2, calculations=true).
properties:
net_changes:
type: object
additionalProperties:
type: string
description: Net change values keyed by period comparison (e.g., "1" for one-month change, "3" for three-month change, "12" for twelve-month change).
pct_changes:
type: object
additionalProperties:
type: string
description: Percent change values keyed by period comparison.
securitySchemes:
apiKeyQuery:
type: apiKey
in: query
name: registrationkey
description: BLS API registration key. Required for Version 2.0 features (catalog metadata, calculations, annual averages, higher rate limits). Obtain for free at https://data.bls.gov/registrationEngine/.
apiKeyBody:
type: apiKey
in: header
name: registrationkey
description: BLS API registration key passed in the JSON request body for POST requests.
externalDocs:
description: BLS Developer Documentation
url: https://www.bls.gov/developers/home.htm