openapi: 3.0.3
info:
  title: BLS Public Data 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.
  - name: Surveys
    description: >-
      Survey metadata and catalog operations for discovering available
      BLS surveys and their series identifiers.
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

  /surveys:
    get:
      operationId: getAllSurveys
      summary: U.S. Bureau of Labor Statistics Get All Surveys
      description: >-
        Retrieve metadata for all available BLS surveys. Returns a list of
        surveys with their abbreviations, names, and descriptions.
      tags:
        - Surveys
      parameters:
        - name: registrationkey
          in: query
          required: false
          description: BLS API registration key.
          schema:
            type: string
            example: abc123def456
      responses:
        '200':
          description: Successful response with list of all surveys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveysResponse'
              examples:
                GetAllSurveys200Example:
                  summary: Default getAllSurveys 200 response
                  x-microcks-default: true
                  value:
                    status: REQUEST_SUCCEEDED
                    responseTime: 132
                    message: []
                    Results:
                      survey:
                        - survey_name: Current Employment Statistics
                          survey_abbreviation: CE
                        - survey_name: Current Population Survey
                          survey_abbreviation: LN
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /surveys/{surveyId}:
    get:
      operationId: getSurveyMetadata
      summary: U.S. Bureau of Labor Statistics Get Survey Metadata
      description: >-
        Retrieve detailed metadata for a specific BLS survey using its
        abbreviation. Returns survey name, description, and available series
        information.
      tags:
        - Surveys
      parameters:
        - name: surveyId
          in: path
          required: true
          description: >-
            Survey abbreviation (e.g., CPS for Current Population Survey,
            CES for Current Employment Statistics, AP for Average Price Data).
          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 survey metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyMetadataResponse'
              examples:
                GetSurveyMetadata200Example:
                  summary: Default getSurveyMetadata 200 response
                  x-microcks-default: true
                  value:
                    status: REQUEST_SUCCEEDED
                    responseTime: 112
                    message: []
                    Results:
                      survey:
                        - survey_name: Current Population Survey
                          survey_abbreviation: CPS
                          survey_title: "Labor Force Statistics from the Current Population Survey"
                          survey_description: "Monthly survey of approximately 60,000 households measuring employment and unemployment."
        '400':
          description: Bad request. Invalid survey ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Survey not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  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.

  schemas:
    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

    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'

    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'

    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'

    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'

    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

    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

    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

    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

    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'

    SurveysResponse:
      title: SurveysResponse
      type: object
      description: Response containing all available BLS surveys.
      properties:
        status:
          type: string
          description: Request status.
          example: REQUEST_SUCCEEDED
        responseTime:
          type: integer
          description: Response time in milliseconds.
          example: 132
        message:
          type: array
          items:
            type: string
        Results:
          type: object
          description: Results containing survey list.
          properties:
            survey:
              type: array
              items:
                $ref: '#/components/schemas/Survey'

    Survey:
      title: Survey
      type: object
      description: Metadata for a BLS survey program.
      properties:
        survey_name:
          type: string
          description: Full name of the BLS survey.
          example: Current Employment Statistics
        survey_abbreviation:
          type: string
          description: Two-letter abbreviation for the survey.
          example: CE
        survey_title:
          type: string
          description: Extended title of the survey.
          example: Current Employment Statistics (National)
        survey_description:
          type: string
          description: Description of the survey's scope and methodology.
          example: Monthly survey of approximately 144,000 businesses and government agencies.

    SurveyMetadataResponse:
      title: SurveyMetadataResponse
      type: object
      description: Response containing metadata for a specific survey.
      properties:
        status:
          type: string
          description: Request status.
          example: REQUEST_SUCCEEDED
        responseTime:
          type: integer
          description: Response time in milliseconds.
          example: 112
        message:
          type: array
          items:
            type: string
        Results:
          type: object
          description: Results containing survey metadata.
          properties:
            survey:
              type: array
              items:
                $ref: '#/components/schemas/Survey'

    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: {}