United States Bureau of Labor Statistics (US BLS)

As the name suggests, the endpoints in this section pertain to data from the United States Bureau of Labor Statistics (US BLS). Parsed data is available nearly all data series in the US BLS such as CPI, PPI, employment figures, prices of specific goods by state, death rates, hiring trends by industry and much more!

Introduction

The APIs in this section provide historical data access through queries and real-time data streaming through subscription connections. For details about the request and response structures, reference the respective GraphQL documentation for that form type in the GraphQL Documentation section.

GraphQL queries require the API key to be set in the headers of each request and subscriptions require them to be set with an initial payload in the connection_init websocket message. For examples of queries and subscriptions, checkout the Quickstart section.

Additionally, user's can learn the various endpoints and test the APIs in the GraphQL playground. To get to the playground pertaining to the data you want, please reference the Playground section.

Pagination

All query endpoints have an identical <endpoint>_count endpoint which can be used to obtain the number of available records for a set of filtering options. The results from the <endpoint>_count endpoint can then be used for pagination purposes in subsequent queries by incrementing the offset value in other non-count query endpoints until all possible values for a query have been retrieved by the client.

Query results are limited to 10 records per page and subscription results are broadcast to clients as they become available and so pagination does not apply to subscription endpoints.

This number may change in the future without prior notice so it is best to use the length of the values returned instead of relying on the static number, especially given that it is possible to create queries that may return less than 10 results in total.

Filtering

Most attributes support filtering. Numeric, date, and datetime values support all equality operators such as >, >=, ==, <=, and < with datetime values specified according to the RFC3339 specification and date values specified in the YYYY-mm-dd format. Datetime values are all in the UTC timezone.

String values can be filtered using regular expressions. Queries support PostgreSQL regex syntax and support the full-suite of regex functionality available in PostgreSQL. Subscriptions use perl-style regex syntax and do not support look-ahead or look-behind patterns for performance reasons. Additionally, regex timeouts are implemented to guarantee service availability. Please see Important Considerations for details about timeouts and other important information when querying.

Important Considerations

All subscriptions must send a keep-alive message to our servers or the connection is at risk of being closed if it is idle for more than an hour. We recommend an interval of once every minute (60s).

Queries must execute in less than 5 seconds or else they will be timed out and an error will be returned to the client. Queries related to retrieving the count of values such as in <endpoint>_count type endpoints must execute in less than 30 seconds or else they will be timed out and an error will be returned to the client. Subscriptions have 1 second per filtered attribute to match the inputted regex pattern or else a regex timeout error will be returned to the client's stream. These safeguards are implemented to prevent abuse of our systems.

Given the availability of regex pattern matching, this means that queries and subscriptions can filter for multiple values in a single request using the | (OR) operator in your pattern. We recommend limiting the number of | clauses to ensure timely delivery of data and to avoid service disruptions.

For a full list of possible errors that can be returned and what they mean, check out the Errors section.

In order to find the series names relating to the series ids of interest, please reference the US BLS site. Various ways are available to find series ids. The easiest way is to reference the most popular series ids.

Playground

This section contains the links to GraphQL playgrounds that can be used for testing, understanding the documentation, and structuring queries and subscriptions for your services. To authenticate your requests, please insert {"api-key": "<YOUR API KEY>"} in the HTTP Headers section on the bottom.

United States Bureau of Labor Statistics

This API contains all the series data from the US BLS.

GraphQL Documentation

Errors

Whenever a request is unsuccessful, BeamAPI will return an error response with an error code and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

GraphQL Query Error Codes

{
    "data": null,
    "extensions": {
        "request-id": "e5a32713-5022-4aec-9312-9a70b7099d42"
    },
    "errors": [
        {
            "message": "Invalid credentials. Make sure you are using a valid api key.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": [
                "filing"
            ],
            "extensions": {
                "code": "api/invalid-credentials-error"
            }
        }
    ]
}

GraphQL Subscription Error Codes

{
    "data": null,
    "errors": [
        {
            "message": "Invalid credentials. Make sure you are using a valid api key.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": [
                "filing"
            ],
            "extensions": {
                "code": "api/invalid-credentials-error"
            }
        }
    ]
}