FRED Provider Extension for the OpenBB Platform

openbb-fred integrates Federal Reserve Economic Data, the database maintained by the Research division of the Federal Reserve Bank of St. Louis, into the Open Data Platform by OpenBB. It reads three St. Louis Fed APIs:

• FRED v1 — https://api.stlouisfed.org/fred — series metadata and observations, series and release search, and the published release tables.
• FRED v2 — https://api.stlouisfed.org/fred/v2 — the cursor-paged release/observations endpoint, which returns every series on a release together with its observations in one call. The key is sent as a bearer token here.
• GeoFRED — https://api.stlouisfed.org/geofred — series groups and regional data.

The extension ships 36 fetchers, a fred router that publishes each of them whenever the namespace extension that would otherwise own it is not installed, a packaged map of FRED releases and their tables, and an OpenBB Workspace dashboard.

Installation

From PyPI:

pip install openbb-fred

For local development from a clone of the OpenBB monorepo, run from this folder:

pip install -e .

Then build the Python static assets so the fred router is registered:

openbb-build

Authentication

A FRED API key is required. Get one at https://fred.stlouisfed.org/docs/api/api_key.html: go to https://fred.stlouisfed.org, click "My Account", create an account or sign in, select "API Keys", then "Request API Key" and describe your use case.

The credential is named fred_api_key. Set it in any of three ways.

At runtime, for the session:

from openbb import obb

obb.user.credentials.fred_api_key = "YOUR_KEY"

In the user settings file, ~/.openbb_platform/user_settings.json:

{
    "credentials": {
        "fred_api_key": "YOUR_KEY"
    }
}

As an environment variable, matched case-insensitively against the credential name:

export FRED_API_KEY=YOUR_KEY

The variable is FRED_API_KEY — credentials are not read under an OPENBB_ prefix, so OPENBB_FRED_API_KEY does not set this credential.

The provider records API_FRED_KEY as the deprecated alias of fred_api_key, for users carrying settings forward from older releases.

Quick Start

The fastest way to get started is by connecting to the OpenBB Workspace as a custom backend.

Start Server

openbb-api

This starts the FastAPI server over localhost on port 6900.

Add to Workspace

See the documentation here for more details.

Click to Open App

The extension serves a bundled dashboard template at /api/v1/fred/apps.json. It is a single app, FRED, with three tabs:

The three widgets on the first two tabs are joined by a symbol param group, defaulting to RSAFS, so clicking a series id in search or in a release table drives the chart.

Widget ids in the packaged template are written for an installation that has openbb-economy, openbb-fixedincome, and openbb-commodity present. When one of those is absent its commands move under /fred/…, so the endpoint serving apps.json prefixes the affected ids with fred_ on the way out — economy_fred_search_fred_obb is served as fred_economy_fred_search_fred_obb. The app therefore works either way.

Coverage

Most of these datasets are served through the Platform's standard models. A standard model is owned by a namespace extension — openbb-economy, openbb-fixedincome, or openbb-commodity — and when that extension is installed, the FRED fetcher registers under the standard model name and answers on that extension's command, selected with provider="fred".

When the owning extension is absent, the same fetcher registers under the standard model name prefixed with Fred — SOFR becomes FredSOFR, BalanceOfPayments becomes FredBalanceOfPayments — and this extension's own router publishes an equivalent command under /fred/…, mirroring the standard command name and sub-path. Installing openbb-fred on its own therefore still exposes every dataset below.

Four models are FRED-native and have no standard-model owner, so they always keep their Fred prefix: FredSearch, FredSeries, FredReleaseTable, and FredRegional. When openbb-economy is installed it hosts them itself, at obb.economy.fred_search, obb.economy.fred_series, obb.economy.fred_release_table, and obb.economy.fred_regional; when it is absent this router publishes them under obb.fred.economy.….

The tables below name each command's standard model. Except for those four, add the Fred prefix to read the name the model registers under in a standalone installation.

Economy — owned by openbb-economy

Installed: obb.economy.<command>(provider="fred"). Standalone: obb.fred.economy.<command>, REST GET /api/v1/fred/economy/<command>.

Economy surveys — owned by openbb-economy

Installed: obb.economy.survey.<command>(provider="fred"). Standalone: obb.fred.economy.survey.<command>.

Fixed Income — owned by openbb-fixedincome

Installed: obb.fixedincome.<path>(provider="fred"). Standalone: obb.fred.fixedincome.<path>.

Commodity — owned by openbb-commodity

Installed: obb.commodity.price.spot(provider="fred"). Standalone: obb.fred.commodity.price.spot.

Release table presentation

One command is not model-backed and is always registered, whichever namespace extensions are installed: obb.fred.economy.release_table, REST GET /api/v1/fred/economy/release_table. It reads its API key from the user settings directly.

Where fred_release_table returns the release's line items as long-form records, this command renders a published table the way the release prints it: one row per line, in the release's own line order, indented to its level, with the periods across the columns, newest first. Each row carries series, symbol, units, and a trend sparkline of the last 36 observations, followed by one dated column per period. Headings left with nothing under them are dropped, and lines the hierarchy cannot otherwise tell apart are named by their units or seasonal adjustment.

Three companion endpoints back the Workspace pickers and are excluded from the OpenAPI schema: release_choices (every release in the packaged map), element_choices (the tables under one release, indented by depth), and frequency_choices (the frequencies one table actually carries). They drive, in order, the Release, Table, and Frequency dropdowns on the release-table widget.

Caching and Rate Limiting

Every FRED request goes through one throttled, retrying, two-tier-cached transport.

• A process-wide throttle holds a minimum gap between successive requests.
• An HTTP 429, or a payload reporting one, is retried with exponential backoff, honouring a Retry-After header when the response carries one. Past the retry budget the request raises an OpenBBError.
• Concurrent cacheable requests for the same URL on the same event loop are collapsed into one in-flight fetch, and the result is shared.
• Tier one is an in-memory LRU cache of deep-copied payloads with a flat lifetime.
• Tier two is an on-disk store with a per-endpoint lifetime, backed by diskcache — a hard dependency of this package. A disk hit is promoted into the memory tier. Empty payloads are never written to either tier.
• The API key is stripped from the URL before it is used as a cache key, so no key is written to disk.

Every one of the 36 models, and the release_table command, takes a per-request use_cache parameter (default True). Setting use_cache=False bypasses both tiers — the response is neither read from nor written to the memory or disk cache.

On-disk lifetimes, before the multiplier is applied:

Environment variables

Disk cache, read on each access:

Throttle, retry, and the in-memory cache, read once when openbb_fred.utils.rate_limiter is first imported — set these before the process starts:

Maintenance: the release map

openbb_fred/assets/release_map.json is a packaged map of every FRED release that is still publishing, each with the tree of sections and tables beneath it, walked down to depth 2. It is what release_choices and element_choices serve, and what the release-table commands fall back to when a table is asked for that a release does not offer.

The package declares a console script to rebuild it:

generate-fred-release-map

Equivalently, without relying on the script being on PATH:

python -m openbb_fred.utils.generate_release_map

It lists every release, drops the ones whose series are all discontinued or stale, walks the remaining releases' element trees, and rewrites the asset. It requires a FRED API key in the user settings and exits with an error without one. That is why the generated file is committed to the repository: a user installing the package cannot rebuild it without a key of their own.

Usage

The examples below are written for an installation that has the namespace extensions present. The standalone equivalents are at the end of this section.

Search for a series id. fred_search runs a full-text search by default, ordered by observation_end so the most recently observed series come first.

from openbb import obb

obb.economy.fred_search(
    query="retail sales",
    search_type="full_text",
    order_by="observation_end",
    sort_order="desc",
    limit=25,
    provider="fred",
).to_df()

Passing a release_id switches the search to that release and lists every series on it.

obb.economy.fred_search(release_id=9, provider="fred").to_df()

Read observations by series id. symbol takes a comma-separated list, and the FRED-side transform, frequency, and aggregation_method parameters are applied by the API.

obb.economy.fred_series(
    symbol="GDP,GDPC1",
    start_date="2015-01-01",
    transform="pc1",
    frequency="q",
    aggregation_method="eop",
    provider="fred",
).to_df()

Read a release table. fred_release_table returns the line items as long-form records. Release 50 is the Employment Situation, and element 462 is its Table A-1.

obb.economy.fred_release_table(
    release_id="50",
    element_id="462",
    provider="fred",
).to_df()

The release_table presentation command renders a table the way the release publishes it, with the periods across the columns. Release 9 is the advance monthly retail sales report, and element 201241 is its seasonally adjusted sales-by-kind-of-business table.

obb.fred.economy.release_table(
    release_id="9",
    element_id="201241",
    frequency="monthly",
    limit=8,
)

Read regional data. Given a series id, fred_regional returns that series alone.

obb.economy.fred_regional(symbol="NYUR", provider="fred").to_df()

To read every region at once, look up the series group the series belongs to — not every FRED series has geographical data — and query that instead. With is_series_group=True, the frequency, region_type, and units parameters are all required.

groups = obb.economy.fred_search(series_id="NYUR", provider="fred").to_df()

obb.economy.fred_regional(
    symbol=groups.series_group[0],
    is_series_group=True,
    region_type=groups.region_type[0],
    units=groups.units[0],
    frequency="a",
    season="nsa",
    provider="fred",
).to_df()

Standard models, answered by FRED.

obb.economy.cpi(country="united_states", transform="yoy", provider="fred").to_df()
obb.fixedincome.rate.sofr(provider="fred").to_df()
obb.commodity.price.spot(provider="fred").to_df()

Bypass the cache for one request, reading neither the memory nor the disk tier.

obb.economy.fred_series(symbol="IORB", use_cache=False, provider="fred").to_df()

With openbb-economy, openbb-fixedincome, and openbb-commodity absent, the same calls read:

obb.fred.economy.fred_search(query="retail sales", provider="fred").to_df()
obb.fred.economy.fred_series(symbol="GDP,GDPC1", provider="fred").to_df()
obb.fred.economy.fred_release_table(release_id="50", provider="fred").to_df()
obb.fred.economy.fred_regional(symbol="NYUR", provider="fred").to_df()
obb.fred.economy.cpi(country="united_states", provider="fred").to_df()
obb.fred.fixedincome.rate.sofr(provider="fred").to_df()
obb.fred.commodity.price.spot(provider="fred").to_df()

obb.fred.economy.release_table(...) is unchanged either way.

Documentation for the OpenBB Platform is available at https://docs.openbb.co/platform.