This document covers the FRED (Federal Reserve Economic Data) and Federal Reserve providers, which supply economic time series data, FOMC meeting documents, primary dealer statistics, and Federal Reserve balance sheet information to the OpenBB Platform.
For information about financial market data providers (FMP, Intrinio), see 4.2. For other economic data sources (BLS, OECD, EconDB, IMF), see 4.3.
The OpenBB Platform integrates two specialized providers for accessing U.S. Federal Reserve and economic data:
Both providers implement the standard fetcher pattern and register their data sources through the provider interface, making them accessible through the economy extension endpoints.
Key Characteristics:
| Provider | Source | Authentication | Fetchers | Data Types |
|---|---|---|---|---|
| FRED | St. Louis Fed API | API Key | 40+ | Time series, search results, release tables |
| Federal Reserve | Federal Reserve Board | None | 13 | Documents, statistics, balance sheet data |
Sources: openbb_platform/providers/fred/openbb_fred/__init__.py58-105 openbb_platform/providers/federal_reserve/openbb_federal_reserve/__init__.py40-60
The FRED provider registers 40+ fetchers covering economic indicators, interest rates, surveys, and bond indices. The provider is defined in fred_provider and includes credentials configuration and fetcher mappings.
Fetcher Symbol Mapping: The fetcher_dict maps standard model names (e.g., "FredSeries", "ConsumerPriceIndex") to their respective fetcher classes. This enables the provider interface to resolve queries like obb.economy.fred_series(symbol="FEDFUNDS", provider="fred").
Sources: openbb_platform/providers/fred/openbb_fred/__init__.py58-105
The FredSeriesFetcher retrieves time series observations for one or more FRED series IDs. This is the most commonly used fetcher for accessing economic data.
Key Parameters:
symbol: Comma-separated FRED series IDs (e.g., "FEDFUNDS,GDP,UNRATE")start_date / end_date: Date range for observationsfrequency: Data aggregation frequency (d, w, m, q, a)aggregation_method: How to aggregate (avg, sum, eop)transform: Data transformation (chg, pc1, pch, log)Transform Options:
chg: Change (period-to-period difference)pc1: Percent change from a year agopch: Percent change from previous periodlog: Natural log transformationSources: openbb_platform/extensions/economy/openbb_economy/economy_router.py151-173 openbb_platform/providers/fred/tests/test_fred_fetchers.py291-298
The FredSearchFetcher supports three distinct search types for discovering FRED series:
Search Parameters:
| Parameter | Description | Example |
|---|---|---|
query | Search term or series ID pattern | "GDP*", "unemployment" |
search_type | Type of search to perform | "series_id", "full_text", "release" |
tag_names | Filter by tags (comma-separated) | "gdp,quarterly" |
exclude_tag_names | Exclude tags | "discontinued" |
filter_variable | Variable to filter on | "frequency", "seasonal_adjustment" |
filter_value | Value for filter variable | "Monthly", "Seasonally Adjusted" |
series_id | Specific series ID (for full_text search) | "NYICLAIMS" |
release_id | Release ID number | "53" (GDP) |
Example Usage:
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py136-149 openbb_platform/extensions/economy/integration/test_economy_python.py274-338
The FredRegionalDataFetcher accesses the GeoFRED API for state and regional economic data. Regional data can be retrieved either as metadata (when no date range is specified) or as time series (with date range).
Regional Data Parameters:
| Parameter | Type | Description |
|---|---|---|
symbol | str | Series group ID or individual series ID |
is_series_group | bool | Whether symbol is a series group |
start_date | date | Start of time series (enables time series mode) |
region_type | str | "state", "msa", "county", etc. |
frequency | str | "a", "q", "m", "w", "d" |
units | str | Units of measurement |
season | str | "sa" (seasonally adjusted) or "nsa" |
Example - Retrieve Unemployment by State:
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py273-301 openbb_platform/extensions/economy/integration/test_economy_python.py459-504
The FredReleaseTableFetcher retrieves structured data from FRED economic releases. Release tables provide hierarchical economic data organized by release ID and element ID.
Usage Pattern:
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py175-199 openbb_platform/extensions/economy/integration/test_economy_python.py954-983
FRED provides several specialized fetchers for economic surveys:
The FRED provider includes two regional manufacturing surveys with detailed topic-based data mapping:
Empire State Manufacturing Survey (New York):
Texas Manufacturing Outlook Survey:
Manufacturing Survey Topics:
Both surveys support multiple topics, each mapped to specific FRED series IDs:
| Topic Category | Examples | Series Count |
|---|---|---|
| Business Outlook | Current, Future (6-month) | 8 series |
| New Orders | Current, Future | 8 series |
| Production | Current, Future | 8 series |
| Hours Worked | Current, Future | 8 series |
| Employment | Current, Future | 8 series |
| Prices | Paid, Received | 8 series |
| Inventories | Current | 4 series |
Each topic includes both seasonally adjusted and non-seasonally adjusted variants, with four data points:
Sources: openbb_platform/providers/fred/openbb_fred/models/manufacturing_outlook_ny.py17-288 openbb_platform/extensions/economy/openbb_economy/survey/survey_router.py113-177
The FRED CPI fetcher implements complex country-to-series mapping for international CPI data. Each country has multiple associated FRED series IDs for different CPI variants.
CPI Mapping Structure:
| Country | Transform | Frequency | Harmonized | Series ID |
|---|---|---|---|---|
| United States | YoY | Monthly | No | CPIAUCSL (All Items) |
| United States | YoY | Monthly | No | CPILFESL (Less Food & Energy) |
| Euro Area | YoY | Monthly | Yes | CP0000EZ19M086NEST |
| Japan | YoY | Monthly | No | JPNCPIALLMINMEI |
| United Kingdom | YoY | Monthly | No | GBRCPIALLMINMEI |
Harmonized vs. Non-Harmonized:
Transform Options:
yoy: Year-over-year percent changeperiod: Period-to-period percent changeSources: openbb_platform/providers/fred/tests/test_fred_fetchers.py78-84 openbb_platform/extensions/economy/integration/test_economy_python.py62-112
The FredBondIndicesFetcher provides access to ICE BofA bond indices tracked by FRED, organized by geographic category and index type.
Bond Index Categories:
Usage Example:
Sources: openbb_platform/providers/fred/tests/test_fred_fetchers.py353-365
The FredRetailPricesFetcher provides Consumer Price Index data for specific retail items and regions, useful for tracking inflation at the product level.
Supported Items:
eggs, milk, bread, ricemeats (beef, pork, chicken)fruits, vegetablesgasoline, electricity, natural_gasapparel, transportationRegions:
all_city (U.S. City Average)northeast, midwest, south, westExample - Track Egg Prices:
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py518-547 openbb_platform/providers/fred/tests/test_fred_fetchers.py343-350
The Federal Reserve provider accesses data directly from the Federal Reserve Board's public datasets, including FOMC documents, primary dealer statistics, balance sheet holdings, and research publications.
Key Distinction: The Federal Reserve provider requires no API key authentication, as it accesses publicly available Federal Reserve Board data.
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/__init__.py40-60
The FOMC documents fetcher provides access to Federal Open Market Committee materials dating back to 1959. The system combines current documents (scraped from federalreserve.gov) with a static historical archive.
FOMC Document Type Definitions:
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/fomc_documents.py8-24
get_current_fomc_documents() Function:
load_historical_fomc_documents() Function:
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/fomc_documents.py27-250 openbb_platform/providers/federal_reserve/openbb_federal_reserve/models/fomc_documents.py1-173
Widget Integration:
The FOMC documents model includes OpenBB Workspace widget configuration for a multi-file PDF viewer:
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/models/fomc_documents.py86-118 openbb_platform/extensions/economy/integration/test_economy_python.py1112-1132
The Federal Reserve Bank of New York publishes weekly statistics on primary dealer positions and fails. The Federal Reserve provider implements complex series ID mappings for these datasets.
Primary dealer positioning data shows the net positions (long minus short) held by primary dealers across various asset classes.
Position Categories and Series Mapping:
The POSITION_GROUPS_TO_SERIES dictionary maps high-level categories to lists of FRED series IDs:
Series Title Mapping:
The POSITION_SERIES_TO_TITLE dictionary maps series IDs to human-readable descriptions:
Data Flow:
Usage Example:
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/models/primary_dealer_positioning.py1-159 openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/primary_dealer_statistics.py1-258
Fails-to-deliver (FTD) and fails-to-receive (FTR) statistics track settlement fails in the primary dealer market. High fail rates can indicate market stress or liquidity issues.
Fails Series Mapping:
Fails Categories:
| Asset Class | FTD Series | FTR Series |
|---|---|---|
| Corporate Securities | PDFTD-CS | PDFTR-CS |
| Agency (Ex-MBS) | PDFTD-FGEM | PDFTR-FGEM |
| Agency MBS | PDFTD-FGM | PDFTR-FGM |
| Treasury (Ex-TIPS) | PDFTD-USTET | PDFTR-USTET |
| TIPS | PDFTD-UST | PDFTR-UST |
Usage Example:
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/primary_dealer_statistics.py6-27 openbb_platform/extensions/economy/openbb_economy/economy_router.py612-642
The FederalReserveCentralBankHoldingsFetcher provides the Federal Reserve's System Open Market Account (SOMA) holdings of Treasury and Agency securities.
Holding Types:
Usage Examples:
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py400-429 openbb_platform/extensions/economy/integration/test_economy_python.py611-646
The Federal Reserve publishes M1 and M2 money supply measures as part of the H.6 statistical release. The FederalReserveMoneyMeasuresFetcher retrieves these aggregates and their components.
Money Supply Components:
Adjustment Options:
adjusted=True: Seasonally adjusted dataadjusted=False: Not seasonally adjustedUsage Example:
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py202-219 openbb_platform/providers/federal_reserve/tests/test_federal_reserve_fetchers.py68-74
The Federal Reserve Bank of San Francisco publishes quarterly total factor productivity (TFP) estimates adjusted for factor utilization (labor effort and capital workweek).
Data Frequency Options:
frequency="quarterly": Time series data (default)frequency="summary": Summary statisticsTFP Components:
Usage Example:
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py716-748 openbb_platform/providers/federal_reserve/tests/test_federal_reserve_fetchers.py179-188
The Survey of Professional Forecasters provides forward-looking inflation expectations. The FederalReserveInflationExpectationsFetcher retrieves these forecasts.
Forecast Horizons:
Usage Example:
Sources: openbb_platform/extensions/economy/openbb_economy/survey/survey_router.py201-214 openbb_platform/providers/federal_reserve/tests/test_federal_reserve_fetchers.py191-200
The economy extension routes commands to the appropriate provider based on the provider parameter. The mapping is established through the provider interface.
Command Decorator Pattern:
Each router command uses the @router.command() decorator with a model parameter that specifies the standard model name:
The Query(**locals()) pattern passes all parameters (including provider_choices which contains the provider name) to the provider interface for resolution.
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py151-173 openbb_platform/extensions/economy/openbb_economy/economy_router.py21-24
FRED supports several data transformations applied server-side before returning results:
| Transform Code | Description | Example |
|---|---|---|
chg | Change (difference) | Value(t) - Value(t-1) |
ch1 | Change from year ago | Value(t) - Value(t-12) |
pch | Percent change | ((Value(t) - Value(t-1)) / Value(t-1)) * 100 |
pc1 | Percent change from year ago | ((Value(t) - Value(t-12)) / Value(t-12)) * 100 |
pca | Compounded annual rate of change | ((Value(t) / Value(t-1))^(frequency) - 1) * 100 |
cch | Continuously compounded rate of change | (ln(Value(t)) - ln(Value(t-1))) * 100 |
cca | Continuously compounded annual rate of change | (ln(Value(t)) - ln(Value(t-1))) * frequency * 100 |
log | Natural log | ln(Value(t)) |
Frequency Aggregation:
When requesting data at a lower frequency than the native frequency, FRED aggregates using the specified method:
avg: Average of values in periodsum: Sum of values in periodeop: End-of-period valueSources: openbb_platform/extensions/economy/openbb_economy/economy_router.py151-173
The provider interface ensures that all fetchers return data conforming to standard models, regardless of the provider. This enables provider switching without breaking code.
Example - Primary Dealer Fails:
All providers implementing PrimaryDealerFails must return data with at minimum date and symbol fields. Provider-specific fields can be added in provider-specific data classes that inherit from the standard model.
Sources: openbb_platform/core/openbb_core/provider/standard_models/primary_dealer_fails.py1-32
Both FRED and Federal Reserve providers use pytest-vcr for recording HTTP interactions. This enables fast, deterministic tests without hitting live APIs.
Test Pattern:
VCR Configuration:
The filter_query_parameters setting replaces real API keys with MOCK_API_KEY in the recorded cassettes, preventing credential leakage.
Sources: openbb_platform/providers/fred/tests/test_fred_fetchers.py66-74 openbb_platform/providers/federal_reserve/tests/test_federal_reserve_fetchers.py48-54
Integration tests verify end-to-end functionality from the economy router through providers to final OBBject output.
Integration Test Pattern:
Integration tests use parametrized fixtures to test multiple provider configurations for each endpoint.
Sources: openbb_platform/extensions/economy/integration/test_economy_python.py341-377 openbb_platform/extensions/tests/utils/integration_tests_testers.py22-51
The FRED and Federal Reserve providers offer comprehensive access to U.S. economic data through standardized interfaces:
FRED Provider Highlights:
Federal Reserve Provider Highlights:
Key Design Patterns:
Sources: openbb_platform/providers/fred/openbb_fred/__init__.py58-105 openbb_platform/providers/federal_reserve/openbb_federal_reserve/__init__.py40-60
Refresh this wiki