OpenBB/openbb_platform/providers/fred

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:

Tab	Contents
Search & Series	The series search and the series chart
Release Tables	Search, the release-table presentation widget, and the series chart
Interest Rates	Yield curve, TIPS yields, EFFR, SOFR, IORB, discount window, ECB rates, mortgage indices, commercial paper, HQM, spot rates, bond indices, and TCM

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

Command	Model
balance_of_payments	BalanceOfPayments
calendar	EconomicCalendar
cpi	ConsumerPriceIndex
pce	PersonalConsumptionExpenditures
retail_prices	RetailPrices
fred_search	FredSearch (native, never re-prefixed)
fred_series	FredSeries (native, never re-prefixed)
fred_release_table	FredReleaseTable (native, never re-prefixed)
fred_regional	FredRegional (native, never re-prefixed)

Economy surveys — owned by openbb-economy

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

Command	Model
economic_conditions_chicago	SurveyOfEconomicConditionsChicago
manufacturing_outlook_ny	ManufacturingOutlookNY
manufacturing_outlook_texas	ManufacturingOutlookTexas
nonfarm_payrolls	NonFarmPayrolls
sloos	SeniorLoanOfficerSurvey
university_of_michigan	UniversityOfMichigan

Fixed Income — owned by openbb-fixedincome

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

Command	Model
bond_indices	BondIndices
mortgage_indices	MortgageIndices
corporate.commercial_paper	CommercialPaper
corporate.hqm	HighQualityMarketCorporateBond
corporate.spot_rates	SpotRate
government.tips_yields	TipsYields
government.yield_curve	YieldCurve
rate.ameribor	Ameribor
rate.dpcredit	DiscountWindowPrimaryCreditRate
rate.ecb	EuropeanCentralBankInterestRates
rate.effr	FederalFundsRate
rate.effr_forecast	PROJECTIONS
rate.estr	EuroShortTermRate
rate.iorb	IORB
rate.overnight_bank_funding	OvernightBankFundingRate
rate.sofr	SOFR
rate.sonia	SONIA
spreads.tcm	TreasuryConstantMaturity
spreads.tcm_effr	SelectedTreasuryConstantMaturity
spreads.treasury_effr	SelectedTreasuryBill

Commodity — owned by openbb-commodity

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

Command	Model
price.spot	CommoditySpotPrices

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.

Parameter	Default	Description
release_id	"9"	The economic release to present
element_id	None	The table within the release; without one, the first table offered is used
frequency	None	annual, quarterly, monthly, weekly, or daily; without one, the interval the table mostly publishes at
limit	8	How many periods to present
symbol	None	Carried for cross-widget grouping, not read
use_cache	True	Whether to read and write the FRED response cache

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:

Endpoint path	Lifetime
/fred/category, /geofred/series/group	7 days
/fred/series, /fred/series/search, /fred/release/series, /fred/releases, /geofred/series/data, /geofred/regional/data	1 day
/fred/release/tables	6 hours
/fred/series/observations	4 hours
/fred/series/updates, and anything unlisted	1 hour

Environment variables

Disk cache, read on each access:

Variable	Default	Effect
OPENBB_FRED_DISK_CACHE	1	Disk caching is off when set to 0, false, or False
OPENBB_FRED_DISK_CACHE_DIR	<cache_directory>/fred	Where the store lives. cache_directory is the OpenBB user preference, itself defaulting to ~/OpenBBUserData/cache
OPENBB_FRED_DISK_CACHE_SIZE	536870912	Size the store is held to, in bytes (512 * 1024 * 1024)
OPENBB_FRED_DISK_TTL_MULTIPLIER	1.0	Factor every lifetime above is scaled by

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

Variable	Default	Effect
OPENBB_FRED_MIN_INTERVAL	0.6	Minimum gap between successive requests, in seconds
OPENBB_FRED_MAX_RETRIES	4	How many times a rate-limited request is retried
OPENBB_FRED_BACKOFF	2.0	Base backoff, in seconds, doubled per attempt
OPENBB_FRED_MAX_BACKOFF	30.0	Ceiling on the computed backoff, in seconds
OPENBB_FRED_CACHE_TTL	300.0	In-memory entry lifetime, in seconds. At 0 or below the memory tier is off
OPENBB_FRED_CACHE_SIZE	512	Maximum in-memory entries. At 0 or below the memory tier is off

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.