United States Board of Federal Reserve (US FED)

As the name suggests, the endpoints in this section pertain to data from the United States Board of Federal Reserve (US FED). Parsed data is available for the most popular and significant form types in the US FED.

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 a total.value attribute which can be used to obtain the number of available records for a specific query. This value can then be used as a reference to increment your offset until all possible values have been received, determined with the final response not containing any records.

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.

Filtering

Our API uses Apache Lucene syntax to filter for documents against an ElasticSearch backend. All attributes within the data attribute of an endpoint supports the full scope of the query engine and can be filtered on.

The data attribute represents the root of the document. For example, filtering for a filing with a specific accession number in the series_data endpoint can be done with the query:

# Write your query or mutation here
query {
    observation {
        took,
        total {
            value
        },
        data {
            value,
            status,
            time_period,
            series_name
        }
    }
}

Query endpoints also offer an aggregation (aggs) attribute to create aggregations that can be used to answer questions such as "What was the percentage change of inflation in the lat year?" To learn more about how to use aggregations see ElasticSearch Aggregations

We offer the full-flexibility of our system to clients. This means that it is possible for users to create complex queries with long execution times. Aggregations can cause this. In order to protect our systems from abuse, all queries will timeout after 5 seconds of execution.

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).

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 of interest, please reference the <DATASET ACRONYM>_series endpoint. Iterating through this endpoint or filtering on the long_description attribute can help you find the series_name of interest. This series_name can then be used in the observation endpoint to get the relevant data. The dataset acronym represents the name of the dataset on the official US Federal Reserve site.

Target interest rate announcements can be streamed in real-time by subscribing to the fomc_release endpoint. Historical interest rates can be accessed by querying the observation endpoint using the series_name attribute of interest in the h15_series endpoint.

Press releases by the Federal Reserve can be monitored through the press_release endpoint.

GraphQL 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.

US FED API

This API contains all information regarding data from the US FED.

GraphQL Documentation

Errors

Whenever a request is unsuccessful, FactIQ 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"
}
}
    ]
}