### API Authentication & Registration

Source: https://context7_llms

Guide for registering an API key and authenticating requests to the BLS Public Data API. Required for accessing v2.0 endpoints with advanced features and higher rate limits.

```APIDOC
## BLS API Registration & Authentication

### Registration

#### Registration Endpoint
https://data.bls.gov/registrationEngine/

#### Registration Requirements
- Valid email address
- Agree to BLS terms of service
- Optional: Organization name and phone number

#### Benefits of Registration (v2.0)
- Increased daily query limit: 500 queries/day
- Support for 50 series per query (vs. single series in v1)
- Support for 20-year data ranges
- Access to optional parameters (calculations, annual averages, metadata)
- Higher request rate: 50 requests per 10 seconds

### API Key Usage

#### Including Your API Key
Add the **registrationkey** parameter to your requests:

```json
{
  "seriesid": ["LNS14000000"],
  "startyear": "2020",
  "endyear": "2023",
  "registrationkey": "your_api_key_here"
}
```

#### Authentication Headers
For authenticated requests:
- **Content-Type**: application/json
- **Authorization**: Optional - Can include key in request body instead

### Rate Limits by Version

#### v1.0 (No Registration Required)
- Daily queries: Unlimited (basic tier)
- Series per query: 1
- Request rate: Standard

#### v2.0 (Registration Required)
- Daily queries: 500
- Series per query: 50
- Years per query: 20
- Request rate: 50 requests per 10 seconds
- Data retention: Queries retained for developer reference

### Contact Information
- **Email**: labstat@bls.gov
- **Phone**: 202-691-5200
- **TRS (Relay Service)**: 7-1-1
- **Website**: https://www.bls.gov/developers/
```

--------------------------------

### HTTP Status Codes & Error Handling

Source: https://context7_llms

Reference guide for BLS API HTTP status codes, error responses, and troubleshooting information. Includes common error scenarios and their resolutions.

```APIDOC
## BLS API Status Codes & Error Handling

### HTTP Status Codes

#### Success Responses
- **200 OK** - Request successful, data returned
  - Check response body for actual status field (may contain REQUEST_SUCCEEDED or REQUEST_FAILED)
  - Data available in results object

#### Client Errors
- **400 Bad Request** - Invalid request format or parameters
  - Check JSON syntax and required fields
  - Verify series IDs are correctly formatted
  - Ensure parameter values are valid (e.g., year format YYYY)

- **404 Not Found** - Series ID not found in database
  - Verify series ID spelling and format
  - Check if series is available for requested time period
  - Consult series list at https://www.bls.gov/help/hlpforma.htm

- **415 Unsupported Media Type** - Wrong Content-Type header
  - For JSON requests: `Content-Type: application/json`
  - For form requests: `Content-Type: application/x-www-form-urlencoded`
  - POST requests require proper Content-Type

- **429 Too Many Requests** - Rate limit exceeded
  - v2.0 limits: 500 queries/day, 50 requests per 10 seconds
  - Implement request queuing and backoff strategy
  - Wait before retrying
  - Consider batching requests efficiently

#### Server Errors
- **500 Internal Server Error** - BLS server error
  - Temporary server issue
  - Retry request after waiting
  - Contact support if persists: labstat@bls.gov

### Response Status Fields
BLS API returns status in response body:
- **REQUEST_SUCCEEDED** - Query processed successfully
- **REQUEST_FAILED** - Query failed, check error messages
- **REQUEST_SHORT_RESULT** - Partial results returned

### Common Error Scenarios

#### Invalid Series ID
```json
{
  "status": "REQUEST_FAILED",
  "message": "Series does not exist",
  "results": null
}
```
Solution: Verify series ID at https://www.bls.gov/developers/

#### Rate Limit Exceeded
```
HTTP/1.1 429 Too Many Requests
Retry-After: 10
```
Solution: Implement exponential backoff, wait before retrying

#### Invalid Content-Type
```
HTTP/1.1 415 Unsupported Media Type
```
Solution: Add correct Content-Type header to POST requests

#### Missing Required Parameters
```json
{
  "status": "REQUEST_FAILED",
  "message": "No series specified",
  "results": null
}
```
Solution: Include seriesid parameter in request

### Troubleshooting Steps
1. Verify API key is active (if using v2.0)
2. Check series IDs are correct and available
3. Confirm request format matches endpoint specifications
4. Review rate limits and request frequency
5. Check Content-Type headers
6. Validate JSON syntax
7. Contact support if issue persists

### Support Contact
- **Email**: labstat@bls.gov
- **Phone**: 202-691-5200
- **TRS**: 7-1-1
```

--------------------------------

### Get Time Series Data (With Date Range - POST)

Source: https://context7_llms

Retrieves time series data for specified series IDs within a given date range (start year and end year) using an HTTP POST request. This allows for targeted data retrieval over specific periods.

```APIDOC
## POST /publicAPI/v1/timeseries/data/ (with date range)

### Description
Retrieves time series data for specified series IDs within a given date range (start year and end year).

### Method
POST

### Endpoint
https://api.bls.gov/publicAPI/v1/timeseries/data/

### Parameters
#### Request Body
- **seriesid** (array of strings) - Required - A list of series IDs to retrieve data for.
- **startyear** (string) - Optional - The starting year for the data retrieval.
- **endyear** (string) - Optional - The ending year for the data retrieval.

### Request Example
```bash
curl -i -X POST -H 'Content-Type: application/json' \
     -d '{"seriesid":["LEU0254555900", "APU0000701111"],
          "startyear":"2002", "endyear":"2012"}' \
     https://api.bls.gov/publicAPI/v1/timeseries/data/
```

### Response
#### Success Response (200)
- **status** (string) - The status of the request (e.g., "REQUEST_SUCCEEDED").
- **response** (object) - Contains the retrieved series data.
  - **series** (array) - An array of objects, each representing a series with its data within the specified date range.
    - **seriesID** (string) - The identifier of the series.
    - **data** (array) - An array of data points for the series.
      - **year** (string) - The year of the data point.
      - **period** (string) - The period within the year.
      - **value** (string) - The data value.
      - **footnotes** (array) - Footnote details.

#### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "response": {
    "series": [
      {
        "seriesID": "LEU0254555900",
        "data": [
          {
            "year": "2002",
            "period": "M01",
            "value": "3.9",
            "footnotes": []
          },
          {
            "year": "2003",
            "period": "M01",
            "value": "4.0",
            "footnotes": []
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### BLS Common Series Reference

Source: https://context7_llms

Quick reference guide for commonly used BLS series identifiers and their descriptions. Includes unemployment rates, consumer price indices, and employment data series codes.

```APIDOC
## BLS Common Series Identifiers

### Frequently Used Series

#### Employment & Unemployment
- **LNS14000000** - Unemployment Rate (percent)
- **CES0000000001** - Total Nonfarm Employment (thousands)
- **LNS12000000** - Employment Level (thousands)
- **LNS13000000** - Labor Force Participation Rate (percent)

#### Consumer Price Index (CPI)
- **CUUR0000SA0** - CPI for All Urban Consumers, All Items (1982-84=100)
- **CUUR0000SA0E** - CPI Energy (1982-84=100)
- **CUUR0000SA0F** - CPI Food (1982-84=100)

#### Producer Price Index (PPI)
- **PPILSD49749** - PPI - All Commodities
- **PPILSD4171** - PPI - Industrial Commodities

#### Other Key Series
- **JTU000000000JOL** - Job Openings (JOLTS)
- **ECI111010** - Employment Cost Index
- **LNS14027662** - Current Population Survey (CPS)

### Series Data Structure
All series follow the format: [Prefix][Classification][Duration]
- Prefix: LN (Labor Force), CES (Employment), CPI, PPI, ECI, JTU, etc.
- Classification: Geographic/industry codes
- Duration: Seasonal adjustments and period identifiers

### Available Datasets
- **CPI** - Consumer Price Index (all items, energy, food, etc.)
- **PPI** - Producer Price Index
- **ECI** - Employment Cost Index
- **CPS/LN** - Current Population Survey Labor statistics
- **JOLTS** - Job Openings and Labor Turnover Survey

### Period Codes
- **M01 - M12** - Monthly data (January - December)
- **Q01 - Q05** - Quarterly data (Q1 - Q5)
- **A01** - Annual data
```

--------------------------------

### Optional Parameters - Date Range and Registration Key

Source: https://context7_llms

Controls the time period for retrieved data using start and end years, and provides authentication via registration key. Version 2.0 supports up to 20 years of data while Version 1.0 supports up to 10 years.

```APIDOC
## GET /timeseries/data - Date Range and Registration Parameters

### Description
Specifies the date range for data retrieval and provides API authentication credentials.

### Parameters
#### Query Parameters
- **startyear** (string) - Optional - Start year in YYYY format. Default: Current year minus 3 years
- **endyear** (string) - Optional - End year in YYYY format. Default: Current year
- **registrationkey** (string) - Required for Version 2.0 features - 32-character alphanumeric API key

### Date Range Limits
| API Version | Maximum Years | Notes |
|-------------|---------------|-------|
| Version 2.0 | 20 years | Recommended for historical analysis |
| Version 1.0 | 10 years | Legacy version with shorter range |

### Default Behavior
- If neither `startyear` nor `endyear` specified: Returns last 3 years of data
- Both parameters accept numeric year values only (YYYY format)

### Registration Key
#### Format
- 32-character alphanumeric string
- Example: `XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`

#### Obtain Registration Key
- Visit: https://data.bls.gov/registrationEngine/
- Required for Version 2.0 features:
  - Catalog metadata
  - Calculations
  - Annual averages
  - Aspects data
  - Extended historical data (beyond 10 years)

### Request Example
```json
{
  "seriesid": ["LAUCN040010000000005"],
  "startyear": "2010",
  "endyear": "2023",
  "registrationkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 145,
  "Results": {
    "series": [
      {
        "seriesID": "LAUCN040010000000005",
        "data": [
          {
            "year": "2023",
            "period": "M12",
            "periodName": "December",
            "value": "25000"
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### BLS API v2 Sample Response with Catalog Data

Source: https://context7_llms

Provides an example of a BLS API v2 JSON response when the 'catalog' parameter is set to true. This response includes detailed catalog information for the requested series, such as series title, seasonality, survey name, and occupation details, in addition to the time series data itself.

```json
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 706,
  "message": [],
  "Results": {
    "series": [
      {
        "seriesID": "WMU00140201020000001300002500",
        "catalog": {
          "series_title": "Average hourly wage for business and financial operations occupations, full-time, in Bloomington, IN",
          "series_id": "WMU00140201020000001300002500",
          "seasonality": "Not Seasonally Adjusted",
          "survey_name": "Modeled Wage Estimates",
          "survey_abbreviation": "WM",
          "measure_data_type": "Average Hourly Wage",
          "commerce_industry": "All industries",
          "occupation": "Business and Financial Operations Occupations",
          "occupation_work_class": "Civilian workers",
          "area": "Bloomington, IN"
        },
        "data": [
          {
            "year": "2018",
            "period": "A01",
            "periodName": "Annual",
            "latest": "true",
            "value": "30.71",
            "aspects": [
              {
                "name": "Relative Standard Error",
                "value": "1.9",
                "footnotes": [{}]
              }
            ],
            "footnotes": [{}]
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### GET /surveys - All Surveys

Source: https://context7_llms

Retrieve a complete list of all available BLS surveys with their abbreviations and full names. This endpoint provides an overview of all survey programs maintained by the BLS.

```APIDOC
## GET /surveys

### Description
Retrieve a list of all BLS surveys including their abbreviations and names.

### Method
GET

### Endpoint
https://api.bls.gov/publicAPI/v2/surveys

### Parameters
None

### Request Example
https://api.bls.gov/publicAPI/v2/surveys

### Response
#### Success Response (200)
- **status** (string) - Request status (e.g., "REQUEST_SUCCEEDED")
- **responseTime** (integer) - Response time in milliseconds
- **message** (array) - Array of messages (empty if no issues)
- **Results** (object) - Container for results
  - **survey** (array) - Array of survey objects
    - **survey_abbreviation** (string) - Abbreviation code for the survey
    - **survey_name** (string) - Full name of the survey

#### Response Example
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 424,
  "message": [],
  "Results": {
    "survey": [
      {
        "survey_abbreviation": "AP",
        "survey_name": "Consumer Price Index - Average Price Data"
      },
      {
        "survey_abbreviation": "BD",
        "survey_name": "Business Employment Dynamics"
      },
      {
        "survey_abbreviation": "BG",
        "survey_name": "Collective Bargaining Agreements-State and Local Government"
      },
      {
        "survey_abbreviation": "BP",
        "survey_name": "Collective Bargaining Agreements-Private Sector"
      }
    ]
  }
}
```

--------------------------------

### Retrieve Single BLS Series with GET Request

Source: https://context7_llms

Fetches data for a single BLS series using HTTP GET method. This is the simplest way to access BLS time series data but limited to one series per request. Requires only the series ID in the URL path.

```bash
curl -i -X GET https://api.bls.gov/publicAPI/v1/timeseries/data/CFU0000008000
```

--------------------------------

### BLS API v2 Series with Optional Parameters (JSON Payload)

Source: https://context7_llms

Demonstrates constructing a JSON payload to retrieve specific time series data from the BLS API v2, including optional parameters like catalog, calculations, annual average, and aspects. This requires a registration key. The example shows how to specify a single series and a date range.

```json
{
  "seriesid": ["WMU00140201020000001300002500", "WMU00140201020000001300002500"],
  "startyear": "2018",
  "endyear": "2018",
  "catalog": true,
  "calculations": true,
  "annualaverage": true,
  "aspects": true,
  "registrationkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

--------------------------------

### GET /publicAPI/v2/timeseries/data/{series_id}

Source: https://context7_llms

Retrieves data for a single time series for the past 3 years. Requires a valid series ID.

```APIDOC
## GET /publicAPI/v2/timeseries/data/{series_id}

### Description
Retrieve data for a single time series for the past 3 years. Requires a valid series ID.

### Method
GET

### Endpoint
`https://api.bls.gov/publicAPI/v2/timeseries/data/{series_id}`

### Parameters
#### Path Parameters
- **series_id** (string) - Required - The unique identifier for the time series.

### Request Example
`GET https://api.bls.gov/publicAPI/v2/timeseries/data/LAUCN040010000000005`

### Response
#### Success Response (200)
- **status** (string) - The status of the request (e.g., "REQUEST_SUCCEEDED").
- **responseTime** (integer) - The time taken to process the request in milliseconds.
- **message** (array) - An array of messages related to the request.
- **Results** (object)
  - **series** (array) - An array of series objects.
    - **seriesID** (string) - The ID of the series.
    - **data** (array) - An array of data points for the series.
      - **year** (string) - The year of the data point.
      - **period** (string) - The period within the year (e.g., "M11" for November).
      - **periodName** (string) - The name of the period (e.g., "November").
      - **value** (string) - The data value.
      - **footnotes** (array) - An array of footnote objects associated with the data point.
        - **code** (string) - The footnote code.
        - **text** (string) - The footnote text.

#### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 16,
  "message": [],
  "Results": {
    "series": [
      {
        "seriesID": "LAUCN040010000000005",
        "data": [
          {
            "year": "2013",
            "period": "M11",
            "periodName": "November",
            "value": "16393",
            "footnotes": [
              {
                "code": "P",
                "text": "Preliminary."
              }
            ]
          },
          {
            "year": "2013",
            "period": "M10",
            "periodName": "October",
            "value": "16536",
            "footnotes": []
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### GET /publicAPI/v1/timeseries/data/

Source: https://context7_llms

Retrieve time series data for a single economic indicator or multiple series from the BLS database. This endpoint supports basic queries for the latest data or specific time periods without requiring authentication.

```APIDOC
## GET /publicAPI/v1/timeseries/data/

### Description
Retrieves time series data from the BLS Public Data API v1. This endpoint allows access to economic indicators such as unemployment rates, consumer price index, and employment data without requiring an API key.

### Method
GET

### Endpoint
https://api.bls.gov/publicAPI/v1/timeseries/data/

### Parameters
#### Query Parameters
- **series_id** (string) - Required - The BLS series identifier (e.g., LNS14000000 for Unemployment Rate)
- **startyear** (string) - Optional - Start year in YYYY format
- **endyear** (string) - Optional - End year in YYYY format

### Request Example
```
GET https://api.bls.gov/publicAPI/v1/timeseries/data/?series_id=LNS14000000&startyear=2020&endyear=2023
```

### Response
#### Success Response (200)
- **status** (string) - Request status
- **responseTime** (integer) - Response time in milliseconds
- **results** (object) - Contains series data
  - **series** (array) - Array of series objects
    - **seriesID** (string) - The series identifier
    - **data** (array) - Array of data points with year, period, value, and footnotes

#### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 45,
  "results": {
    "series": [
      {
        "seriesID": "LNS14000000",
        "data": [
          {
            "year": "2023",
            "period": "M12",
            "value": "3.7",
            "footnotes": []
          }
        ]
      }
    ]
  }
}
```

### Error Responses
- **404** - Series not found
- **500** - Server error
```

--------------------------------

### Get Time Series Data (Multiple Series - POST)

Source: https://context7_llms

Retrieves time series data for multiple specified series IDs using an HTTP POST request. This is efficient for fetching data for several series in a single call.

```APIDOC
## POST /publicAPI/v1/timeseries/data/

### Description
Retrieves time series data for multiple specified series IDs using a JSON payload.

### Method
POST

### Endpoint
https://api.bls.gov/publicAPI/v1/timeseries/data/

### Parameters
#### Request Body
- **seriesid** (array of strings) - Required - A list of series IDs to retrieve data for.

### Request Example
```bash
curl -i -X POST -H 'Content-Type: application/json' \
     -d '{"seriesid": ["CFU0000008000","LEU0254555900"]}' \
     https://api.bls.gov/publicAPI/v1/timeseries/data/
```

### Response
#### Success Response (200)
- **status** (string) - The status of the request (e.g., "REQUEST_SUCCEEDED").
- **response** (object) - Contains the retrieved series data.
  - **series** (array) - An array of objects, each representing a series with its data.
    - **seriesID** (string) - The identifier of the series.
    - **data** (array) - An array of data points for the series.
      - **year** (string) - The year of the data point.
      - **period** (string) - The period within the year.
      - **value** (string) - The data value.
      - **footnotes** (array) - Footnote details.

#### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "response": {
    "series": [
      {
        "seriesID": "CFU0000008000",
        "data": [
          {
            "year": "2023",
            "period": "M01",
            "value": "150.2",
            "footnotes": []
          }
        ]
      },
      {
        "seriesID": "LEU0254555900",
        "data": [
          {
            "year": "2023",
            "period": "M01",
            "value": "3.5",
            "footnotes": []
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Retrieve Multiple BLS Series with POST Request

Source: https://context7_llms

Queries multiple series in a single API request using HTTP POST with JSON payload. Supports up to 50 series per request in v2.0, reducing API calls and improving performance compared to individual GET requests.

```bash
curl -i -X POST -H 'Content-Type: application/json' \
     -d '{"seriesid": ["CFU0000008000","LEU0254555900"]}' \
     https://api.bls.gov/publicAPI/v1/timeseries/data/
```

--------------------------------

### GET /surveys/{survey_abbreviation} - Single Survey

Source: https://context7_llms

Retrieve detailed metadata for a specific BLS survey. Returns information about the survey's configuration, including whether it supports net change, percent change calculations, and annual averages.

```APIDOC
## GET /surveys/{survey_abbreviation}

### Description
Retrieve metadata associated with a single BLS survey including configuration options and capabilities.

### Method
GET

### Endpoint
https://api.bls.gov/publicAPI/v2/surveys/{survey_abbreviation}

### Parameters
#### Path Parameters
- **survey_abbreviation** (string) - Required - The survey abbreviation code (e.g., "TU")

### Request Example
https://api.bls.gov/publicAPI/v2/surveys/TU

### Response
#### Success Response (200)
- **status** (string) - Request status (e.g., "REQUEST_SUCCEEDED")
- **responseTime** (integer) - Response time in milliseconds
- **message** (array) - Array of messages (empty if no issues)
- **Results** (object) - Container for results
  - **survey** (array) - Array containing survey metadata object
    - **survey_name** (string) - Full name of the survey
    - **survey_abbreviation** (string) - Abbreviation code for the survey
    - **allowsNetChange** (string) - Whether the survey supports net change calculations
    - **allowsPercentChange** (string) - Whether the survey supports percent change calculations
    - **hasAnnualAverages** (string) - Whether the survey provides annual averages

#### Response Example
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 46,
  "message": [],
  "Results": {
    "survey": [
      {
        "survey_name": "American Time Use",
        "survey_abbreviation": "TU",
        "allowsNetChange": "false",
        "allowsPercentChange": "false",
        "hasAnnualAverages": "false"
      }
    ]
  }
}
```

--------------------------------

### Query BLS API v2 with Registration and Advanced Features

Source: https://context7_llms

Uses API v2 with registered API key to access premium features including catalog metadata, calculations, and annual averages. Requires free registration at data.bls.gov and provides 500 daily queries versus 25 for unregistered users.

```bash
curl -i -X POST -H 'Content-Type: application/json' \
     -d '{"seriesid":["LNS14000000","CUUR0000SA0"],
          "registrationkey":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "catalog":true, "calculations":true, "annualaverage":true}' \
     https://api.bls.gov/publicAPI/v2/timeseries/data/
```

--------------------------------

### Get Time Series Data (Single Series - GET)

Source: https://context7_llms

Retrieves time series data for a single specified series ID using an HTTP GET request. This method is suitable for simple, single data point lookups.

```APIDOC
## GET /publicAPI/v1/timeseries/data/

### Description
Retrieves time series data for a single specified series ID.

### Method
GET

### Endpoint
https://api.bls.gov/publicAPI/v1/timeseries/data/{seriesId}

### Parameters
#### Path Parameters
- **seriesId** (string) - Required - The unique identifier for the time series data to retrieve.

### Request Example
```bash
curl -i -X GET https://api.bls.gov/publicAPI/v1/timeseries/data/CFU0000008000
```

### Response
#### Success Response (200)
- **seriesId** (string) - The identifier of the requested series.
- **data** (array) - An array of objects, where each object represents a data point with date and value.
  - **year** (string) - The year of the data point.
  - **period** (string) - The period within the year (e.g., 'M01' for January).
  - **value** (string) - The data value for the period.
  - **footnotes** (array) - An array of footnote objects associated with the data point.
    - **symbol** (string) - The footnote symbol.
    - **methoxy** (string) - The footnote text.

#### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "response": {
    "series": [
      {
        "seriesID": "CFU0000008000",
        "data": [
          {
            "year": "2023",
            "period": "M01",
            "value": "150.2",
            "footnotes": []
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### BLS API v2.0 Data Retrieval with Options

Source: https://context7_llms

Demonstrates a POST request to the v2.0 API endpoint, including options like catalog, calculations, and annual average. This is the recommended version for production use due to higher limits and enhanced features.

```APIDOC
## POST /publicAPI/v2/timeseries/data/

### Description
Retrieves time series data using the v2.0 API, which supports additional options for enhanced data retrieval and processing. This version is recommended for production environments.

### Method
POST

### Endpoint
https://api.bls.gov/publicAPI/v2/timeseries/data/

### Parameters
#### Request Body
- **registrationkey** (string) - Required - Your registered API key.
- **seriesid** (array of strings) - Required - A list of series IDs to retrieve data for.
- **catalog** (boolean) - Optional - If true, returns human-readable descriptions for series (available for Data Finder surveys only).
- **calculations** (boolean) - Optional - If true, includes calculated fields in the response, saving post-processing work.
- **annualaverage** (boolean) - Optional - If true, includes the annual average value for the series.

### Request Example
```bash
curl -i -X POST -H 'Content-Type: application/json' \
     -d '{"registrationkey":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "seriesid":["LNS14000000", "CUUR0000SA0"],
          "catalog":true, "calculations":true, "annualaverage":true}' \
     https://api.bls.gov/publicAPI/v2/timeseries/data/
```

### Response
#### Success Response (200)
- **status** (string) - The status of the request (e.g., "REQUEST_SUCCEEDED").
- **response** (object) - Contains the retrieved series data and metadata.
  - **series** (array) - An array of objects, each representing a series.
    - **seriesID** (string) - The identifier of the series.
    - **data** (array) - An array of data points for the series.
      - **year** (string) - The year of the data point.
      - **period** (string) - The period within the year.
      - **value** (string) - The data value.
      - **calculated_value** (string, optional) - Calculated value if `calculations=true`.
      - **annual_average** (string, optional) - Annual average value if `annualaverage=true`.
      - **footnotes** (array) - Footnote details.
    - **catalog** (object, optional) - Metadata about the series if `catalog=true`.
      - **series_id** (string)
      - **series_title** (string)
      - **survey_name** (string)
      - **data_type_name** (string)
      - **measure_name** (string)
      - **release_date** (string)

#### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "response": {
    "series": [
      {
        "seriesID": "LNS14000000",
        "data": [
          {
            "year": "2023",
            "period": "M01",
            "value": "3.4",
            "calculated_value": "3.4",
            "annual_average": "3.6",
            "footnotes": []
          }
        ],
        "catalog": {
          "series_id": "LNS14000000",
          "series_title": "Unemployment Rate (Seasonally Adjusted)",
          "survey_name": "Labor Force Statistics (National)",
          "data_type_name": "Rate",
          "measure_name": "Unemployment Rate",
          "release_date": "2024-02-02T08:30:00Z"
        }
      }
    ]
  }
}
```
```

--------------------------------

### GET /timeseries/popular - Popular Series

Source: https://context7_llms

Retrieve a list of the 25 most popular BLS series. Can optionally filter by a specific survey using the survey parameter to get popular series within that survey.

```APIDOC
## GET /timeseries/popular

### Description
Retrieve a list of series IDs for the 25 most popular BLS series. Optionally filter by a specific survey.

### Method
GET

### Endpoint
https://api.bls.gov/publicAPI/v2/timeseries/popular

### Parameters
#### Query Parameters
- **survey** (string) - Optional - Survey abbreviation to get popular series for a specific survey (e.g., "LA")

### Request Example (All Popular Series)
https://api.bls.gov/publicAPI/v2/timeseries/popular

### Request Example (Survey-Specific)
https://api.bls.gov/publicAPI/v2/timeseries/popular?survey=LA

### Response
#### Success Response (200)
- **status** (string) - Request status (e.g., "REQUEST_SUCCEEDED")
- **responseTime** (integer) - Response time in milliseconds
- **message** (array) - Array of messages (empty if no issues)
- **Results** (object) - Container for results
  - **series** (array) - Array of popular series objects
    - **seriesID** (string) - The series ID

#### Response Example (All Popular)
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 29,
  "message": [],
  "Results": {
    "series": [
      {"seriesID": "LNS14000000"},
      {"seriesID": "CUUR0000SA0"},
      {"seriesID": "CES0000000001"},
      {"seriesID": "LNS14000006"},
      {"seriesID": "CUSR0000SA0"}
    ]
  }
}

#### Response Example (LA Survey)
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 38,
  "message": [],
  "Results": {
    "series": [
      {"seriesID": "LASST060000000000003"},
      {"seriesID": "LASST260000000000003"},
      {"seriesID": "LASST480000000000003"}
    ]
  }
}
```

--------------------------------

### Client Libraries & SDKs

Source: https://context7_llms

Third-party libraries and SDKs available for accessing the BLS API across multiple programming languages including Python, R, Node.js, Java, and Ruby.

```APIDOC
## BLS API Client Libraries

### Available Libraries by Language

#### Python
- **blsAPI** - Official Python library for BLS API access
  - PyPI: https://pypi.org/project/blsapi/
  - Supports both v1 and v2 endpoints
  - Installation: `pip install blsapi`
  - Usage: Import and query series with simple methods

#### R
- **blsAPI** - R package for BLS API queries
  - CRAN: https://cran.r-project.org/web/packages/blsAPI/
  - Provides functions for series retrieval and data manipulation
  - Installation: `install.packages("blsAPI")`

- **blscrapeR** - Web scraping alternative for BLS data
  - CRAN: https://cran.r-project.org/web/packages/blscrapeR/
  - Useful for supplementary data collection

#### Node.js
- **Various npm packages** available for BLS API integration
  - Search npm registry for "bls" packages
  - Common packages: bls, node-bls, bls-api
  - Installation: `npm install [package-name]`

#### Java
- **Custom implementations** available
  - No official Java library
  - Use standard HTTP libraries (HttpClient, okhttp, etc.)
  - Build REST requests manually or use frameworks like Spring

#### Ruby
- **BLS gem** - Ruby gem for API access
  - Gemfile: `gem 'bls'`
  - Installation: `bundle install`
  - Provides convenient methods for querying series data

### Library Features
- Simplified API request building
- Automatic error handling
- Data parsing and formatting
- Series caching (in some libraries)
- Rate limit management
- Authentication support (API key handling)

### General Usage Pattern
```
1. Install library for your language
2. Authenticate with API key (if using v2.0)
3. Specify series IDs to query
4. Set optional parameters (year range, calculations, etc.)
5. Execute query and process results
```

### Official Documentation
- **BLS Developers Portal**: https://www.bls.gov/developers/
- **API Documentation**: https://www.bls.gov/developers/
- **Support**: labstat@bls.gov
```

--------------------------------

### Query Single BLS Series with Unix curl GET Request

Source: https://context7_llms

Retrieves time series data for a single series ID using HTTP GET method with curl. No authentication required for basic queries. Returns JSON response with time series data points ordered by most recent first.

```bash
curl -i -X GET https://api.bls.gov/publicAPI/v2/timeseries/data/CFU0000008000
```

--------------------------------

### Rate Limits and Quotas

Source: https://context7_llms

Outlines the rate limits and quotas for both registered (Version 2.0) and unregistered (Version 1.0) API users, including daily limits, series per query, and request rates.

```APIDOC
## Version 2.0 (Registered)

- Daily query limit: 500 queries per day
- Series per query: 50 series maximum
- Years per query: 20 years maximum
- Request rate: 50 requests per 10 seconds
- Renewal: Must renew registration at least once per year

## Version 1.0 (Unregistered)

- Daily query limit: 25 queries per day
- Series per query: 25 series maximum
- Years per query: 10 years maximum
- Request rate: 50 requests per 10 seconds

## Rate Limiting Behavior

- Exceeding 50 requests per 10 seconds results in a 429 error.
- Daily limits reset at midnight (Eastern Time Zone).
- Queries count toward the daily limit regardless of success or failure.

## Best Practices

- Use batch requests (multiple series per query) to reduce query count.
- Implement exponential backoff when receiving 429 errors.
- Cache responses to avoid redundant API calls.
- Use Version 2.0 for production applications.
```

--------------------------------

### POST /publicAPI/v2/timeseries/data/

Source: https://context7_llms

Submit advanced queries to retrieve multiple time series with optional parameters including calculations, annual averages, and metadata. Requires API key registration and supports up to 50 series per query with enhanced rate limits.

```APIDOC
## POST /publicAPI/v2/timeseries/data/

### Description
Advanced endpoint for querying multiple BLS time series with optional parameters for calculations, annual averages, and metadata retrieval. Requires API key registration and supports enhanced filtering options.

### Method
POST

### Endpoint
https://api.bls.gov/publicAPI/v2/timeseries/data/

### Headers
- **Content-Type** (string) - Required - application/json
- **Authorization** (string) - Optional - API key authentication

### Parameters
#### Request Body
- **seriesid** (array) - Required - Array of BLS series identifiers (max 50 per query)
- **startyear** (string) - Optional - Start year in YYYY format (max 20 years)
- **endyear** (string) - Optional - End year in YYYY format (max 20 years)
- **registrationkey** (string) - Optional - Your registered API key
- **calculations** (boolean) - Optional - Include net and percent changes
- **annualaverage** (boolean) - Optional - Include annual average calculations
- **catalog** (boolean) - Optional - Include series metadata
- **aspects** (boolean) - Optional - Include additional aspects

### Request Example
```json
{
  "seriesid": ["LNS14000000", "CUUR0000SA0", "CES0000000001"],
  "startyear": "2020",
  "endyear": "2023",
  "registrationkey": "your_api_key_here",
  "calculations": true,
  "annualaverage": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Request status (REQUEST_SUCCEEDED)
- **responseTime** (integer) - Response time in milliseconds
- **results** (object) - Contains multiple series data
  - **series** (array) - Array of series objects
    - **seriesID** (string) - The series identifier
    - **data** (array) - Array of data points with calculations if requested

#### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 120,
  "results": {
    "series": [
      {
        "seriesID": "LNS14000000",
        "data": [
          {
            "year": "2023",
            "period": "M12",
            "value": "3.7",
            "calculations": {
              "net_change": "0.2",
              "pct_changes": "5.7"
            }
          }
        ]
      }
    ]
  }
}
```

### Error Responses
- **200 with error status** - Query successful but contains errors
- **400** - Invalid request format
- **415** - Unsupported Content-Type
- **429** - Rate limit exceeded (500 queries/day, 50 requests/10 seconds)
- **404** - Series not found
- **500** - Server error

### Rate Limits (v2.0)
- Daily limit: 500 queries
- Series per query: 50 maximum
- Years per query: 20 maximum
- Request rate: 50 requests per 10 seconds
```

--------------------------------

### Optional Parameters - Catalog

Source: https://context7_llms

Returns comprehensive metadata about a series including title, seasonality, survey information, measure type, geography, and industry classification. Requires registration key and is only available for surveys included in the BLS Data Finder tool.

```APIDOC
## GET /timeseries/data - Catalog Parameter

### Description
Returns comprehensive metadata about the series including title, seasonality, survey name, measure type, geography, industry, and occupation information.

### Parameters
#### Query Parameters
- **catalog** (boolean) - Optional - Set to `true` to include series metadata. Default: `false`
- **registrationkey** (string) - Required - 32-character API key from https://data.bls.gov/registrationEngine/

### Availability
- Only available for surveys included in the BLS Data Finder tool
- Requires valid registration key

### Catalog Response Fields
- **series_title** (string) - Full title of the series
- **series_id** (string) - The BLS series identifier
- **seasonality** (string) - Seasonal adjustment indicator
- **survey_name** (string) - Name of the survey
- **survey_abbreviation** (string) - Survey abbreviation
- **measure_data_type** (string) - Type of measurement
- **commerce_industry** (string) - Industry classification
- **occupation** (string) - Occupation classification
- **occupation_work_class** (string) - Work class for occupation data
- **area** (string) - Geographic area description

### Request Example
```json
{
  "seriesid": ["LAUCN040010000000005"],
  "startyear": "2020",
  "endyear": "2023",
  "catalog": true,
  "registrationkey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

### Response Example
```json
{
  "status": "REQUEST_SUCCEEDED",
  "Results": {
    "series": [
      {
        "seriesID": "LAUCN040010000000005",
        "catalog": {
          "series_title": "Employment Level - Apache County, AZ",
          "survey_name": "Local Area Unemployment Statistics",
          "seasonality": "Not Seasonally Adjusted",
          "area": "Apache County, Arizona"
        },
        "data": []
      }
    ]
  }
}
```
```