U.S. Bureau of Labor Statistics Series API

openapi: 3.0.3
info:
  title: BLS Public Data Series API
  description: The U.S. Bureau of Labor Statistics (BLS) Public Data API provides programmatic access to published historical time series data covering employment, unemployment, prices, wages, and other labor market indicators. The API returns JSON data and supports both Version 1 (no registration) and Version 2 (requires free registration for higher limits and additional features).
  version: '2.0'
  contact:
    name: BLS Developer Support
    url: https://www.bls.gov/developers/
    email: webmaster@bls.gov
  license:
    name: Public Domain
    url: https://www.bls.gov/
  x-generated-from: documentation
servers:
- url: https://api.bls.gov/publicAPI/v2
  description: BLS Public Data API Version 2 (registration required)
- url: https://api.bls.gov/publicAPI/v1
  description: BLS Public Data API Version 1 (no registration)
security:
- ApiKeyQuery: []
- {}
tags:
- name: Series
  description: Time series data operations for retrieving labor statistics across BLS surveys including employment, CPI, wages, and more.
paths:
  /timeseries/data/{seriesId}:
    get:
      operationId: getSingleSeries
      summary: U.S. Bureau of Labor Statistics Get Single Series Data
      description: Retrieve time series data for a single BLS series ID. Returns historical data points including year, period, and value. Optional parameters allow filtering by year range and requesting additional metadata.
      tags:
      - Series
      parameters:
      - name: seriesId
        in: path
        required: true
        description: A single BLS series ID (e.g., LAUCN040010000000005 for local area unemployment, CUUR0000SA0 for CPI All Urban Consumers).
        schema:
          type: string
          example: CUUR0000SA0
      - name: startyear
        in: query
        required: false
        description: First year of data to retrieve in YYYY format.
        schema:
          type: string
          example: '2020'
      - name: endyear
        in: query
        required: false
        description: Last year of data to retrieve in YYYY format.
        schema:
          type: string
          example: '2025'
      - name: registrationkey
        in: query
        required: false
        description: BLS API registration key obtained from data.bls.gov/registrationEngine/. Required for Version 2 features such as catalog, calculations, and annual averages.
        schema:
          type: string
          example: abc123def456
      - name: catalog
        in: query
        required: false
        description: Set to true to include series catalog metadata in the response.
        schema:
          type: boolean
          example: false
      - name: calculations
        in: query
        required: false
        description: Set to true to include net and percent change calculations.
        schema:
          type: boolean
          example: false
      - name: annualaverage
        in: query
        required: false
        description: Set to true to include annual averages in the response.
        schema:
          type: boolean
          example: false
      - name: aspects
        in: query
        required: false
        description: Set to true to include aspects metadata for the series.
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: Successful response with time series data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesResponse'
              examples:
                GetSingleSeries200Example:
                  summary: Default getSingleSeries 200 response
                  x-microcks-default: true
                  value:
                    status: REQUEST_SUCCEEDED
                    responseTime: 178
                    message: []
                    Results:
                      series:
                      - seriesID: CUUR0000SA0
                        data:
                        - year: '2025'
                          period: M03
                          periodName: March
                          value: '318.449'
                          footnotes:
                          - code: P
                            text: Preliminary
                          latest: 'true'
        '400':
          description: Bad request. Invalid series ID or parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /timeseries/data/:
    post:
      operationId: getMultipleSeries
      summary: U.S. Bureau of Labor Statistics Get Multiple Series Data
      description: Retrieve time series data for one or more BLS series IDs in a single request. Version 2 supports up to 50 series per request and up to 20 years of data. Version 1 supports up to 25 series and fewer features.
      tags:
      - Series
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultipleSeriesRequest'
            examples:
              GetMultipleSeriesRequestExample:
                summary: Default getMultipleSeries request
                x-microcks-default: true
                value:
                  seriesid:
                  - LNS14000000
                  - LNS11000000
                  startyear: '2020'
                  endyear: '2025'
                  registrationkey: abc123def456
                  catalog: false
                  calculations: true
                  annualaverage: false
      responses:
        '200':
          description: Successful response with data for all requested series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesResponse'
              examples:
                GetMultipleSeries200Example:
                  summary: Default getMultipleSeries 200 response
                  x-microcks-default: true
                  value:
                    status: REQUEST_SUCCEEDED
                    responseTime: 243
                    message: []
                    Results:
                      series:
                      - seriesID: LNS14000000
                        data:
                        - year: '2025'
                          period: M03
                          periodName: March
                          value: '4.2'
                          footnotes: []
                          latest: 'true'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /timeseries/popular:
    get:
      operationId: getPopularSeries
      summary: U.S. Bureau of Labor Statistics Get Popular Series
      description: Retrieve the 25 most popular BLS series IDs. Can optionally specify a survey abbreviation to get popular series for a specific survey.
      tags:
      - Series
      parameters:
      - name: survey
        in: query
        required: false
        description: Survey abbreviation to filter popular series (e.g., CPS for Current Population Survey, CES for Current Employment Statistics).
        schema:
          type: string
          example: CPS
      - name: registrationkey
        in: query
        required: false
        description: BLS API registration key.
        schema:
          type: string
          example: abc123def456
      responses:
        '200':
          description: Successful response with popular series IDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PopularSeriesResponse'
              examples:
                GetPopularSeries200Example:
                  summary: Default getPopularSeries 200 response
                  x-microcks-default: true
                  value:
                    status: REQUEST_SUCCEEDED
                    responseTime: 89
                    message: []
                    Results:
                      series:
                      - seriesID: LNS14000000
                        catalog:
                          series_title: (Seas) Unemployment Rate
                          survey_name: Labor Force Statistics from the Current Population Survey
                          measure_data_type: Unemployment rate
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SeriesResults:
      title: SeriesResults
      type: object
      description: Container for series data results.
      properties:
        series:
          type: array
          description: Array of series data objects.
          items:
            $ref: '#/components/schemas/SeriesData'
    PeriodCalculations:
      title: PeriodCalculations
      type: object
      description: Calculations for a specific data point.
      properties:
        net_changes:
          type: object
          description: Net change from prior periods.
          additionalProperties:
            type: string
        pct_changes:
          type: object
          description: Percent change from prior periods.
          additionalProperties:
            type: string
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Error response from the BLS API.
      properties:
        status:
          type: string
          description: Request failure status.
          example: REQUEST_FAILED
        responseTime:
          type: integer
          description: Response time in milliseconds.
          example: 45
        message:
          type: array
          description: Array of error messages explaining the failure.
          items:
            type: string
          example:
          - Series does not exist
        Results:
          type: object
          description: Empty results on failure.
          properties:
            series:
              type: array
              items: {}
    Footnote:
      title: Footnote
      type: object
      description: A footnote code and text applicable to a data point.
      properties:
        code:
          type: string
          description: Footnote code letter.
          example: P
        text:
          type: string
          description: Footnote explanation text.
          example: Preliminary
    PopularSeriesResponse:
      title: PopularSeriesResponse
      type: object
      description: Response containing popular BLS series.
      properties:
        status:
          type: string
          description: Request status.
          example: REQUEST_SUCCEEDED
        responseTime:
          type: integer
          description: Response time in milliseconds.
          example: 89
        message:
          type: array
          items:
            type: string
        Results:
          type: object
          description: Results containing popular series list.
          properties:
            series:
              type: array
              items:
                type: object
                properties:
                  seriesID:
                    type: string
                    description: BLS series identifier.
                    example: LNS14000000
                  catalog:
                    $ref: '#/components/schemas/SeriesCatalog'
    SeriesCatalog:
      title: SeriesCatalog
      type: object
      description: Catalog metadata describing a BLS series.
      properties:
        series_id:
          type: string
          description: BLS series identifier.
          example: LNS14000000
        seasonality:
          type: string
          description: Seasonality adjustment type (Seasonally Adjusted, Not Seasonally Adjusted).
          example: Seasonally Adjusted
        series_title:
          type: string
          description: Descriptive title for the series.
          example: (Seas) Unemployment Rate
        measure_data_type:
          type: string
          description: Type of measure reported.
          example: Unemployment rate
        commerce_industry:
          type: string
          description: Industry classification if applicable.
          example: ''
        occupation:
          type: string
          description: Occupation classification if applicable.
          example: ''
        survey_name:
          type: string
          description: Full name of the BLS survey providing this series.
          example: Labor Force Statistics from the Current Population Survey
        survey_abbreviation:
          type: string
          description: Abbreviation code for the BLS survey.
          example: LN
    SeriesData:
      title: SeriesData
      type: object
      description: Data for a single BLS time series.
      properties:
        seriesID:
          type: string
          description: BLS series identifier.
          example: CUUR0000SA0
        catalog:
          $ref: '#/components/schemas/SeriesCatalog'
        data:
          type: array
          description: Array of data points for the series.
          items:
            $ref: '#/components/schemas/DataPoint'
        calculations:
          $ref: '#/components/schemas/Calculations'
    SeriesResponse:
      title: SeriesResponse
      type: object
      description: Standard BLS API response containing time series data.
      properties:
        status:
          type: string
          description: Request status (REQUEST_SUCCEEDED, REQUEST_FAILED, REQUEST_NOT_PROCESSED).
          example: REQUEST_SUCCEEDED
        responseTime:
          type: integer
          description: Server response time in milliseconds.
          example: 178
        message:
          type: array
          description: Array of informational or error messages.
          items:
            type: string
        Results:
          $ref: '#/components/schemas/SeriesResults'
    MultipleSeriesRequest:
      title: MultipleSeriesRequest
      type: object
      required:
      - seriesid
      description: Request body for fetching multiple time series.
      properties:
        seriesid:
          type: array
          description: Array of BLS series IDs to retrieve. Version 2 supports up to 50 series; Version 1 supports up to 25 series.
          items:
            type: string
          example:
          - LNS14000000
          - CUUR0000SA0
        startyear:
          type: string
          description: First year of data to retrieve in YYYY format.
          example: '2020'
        endyear:
          type: string
          description: Last year of data to retrieve in YYYY format.
          example: '2025'
        registrationkey:
          type: string
          description: BLS API Version 2 registration key.
          example: abc123def456
        catalog:
          type: boolean
          description: Include series catalog metadata in the response.
          example: false
        calculations:
          type: boolean
          description: Include net change and percent change calculations.
          example: true
        annualaverage:
          type: boolean
          description: Include annual average values.
          example: false
        aspects:
          type: boolean
          description: Include aspects metadata.
          example: false
    Calculations:
      title: Calculations
      type: object
      description: Net and percent change calculations for a series.
      properties:
        net_changes:
          type: object
          description: Net change values by period label.
          additionalProperties:
            type: string
        pct_changes:
          type: object
          description: Percent change values by period label.
          additionalProperties:
            type: string
    DataPoint:
      title: DataPoint
      type: object
      description: A single time series data observation.
      properties:
        year:
          type: string
          description: Calendar year of the observation.
          example: '2025'
        period:
          type: string
          description: Period code in M01-M13 format (M13 is annual average).
          example: M03
        periodName:
          type: string
          description: Human-readable period name.
          example: March
        value:
          type: string
          description: The data value as a string. May be "-" if data is not available.
          example: '318.449'
        footnotes:
          type: array
          description: Array of footnotes applicable to this data point.
          items:
            $ref: '#/components/schemas/Footnote'
        latest:
          type: string
          description: Indicates if this is the most recent data point.
          example: 'true'
        calculations:
          $ref: '#/components/schemas/PeriodCalculations'
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: registrationkey
      description: Free BLS API registration key. Register at https://data.bls.gov/registrationEngine/ to obtain a key for Version 2 API features.