The Economy Extension provides access to macroeconomic data, indicators, and statistics from multiple data providers. It implements a hierarchical router structure with commands for GDP, CPI, unemployment, interest rates, and other economic indicators.
The Economy Extension is located at openbb_platform/extensions/economy/ and follows the standard extension architecture pattern. It consists of a main router that includes sub-routers for specialized economic data categories.
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py1-27 openbb_platform/extensions/economy/openbb_economy/gdp/gdp_router.py1-84
The main economy router is defined in openbb_platform/extensions/economy/openbb_economy/economy_router.py using the Router class from the core framework:
Each command is registered using the @router.command() decorator with a model parameter that specifies the standard data model.
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py24-27
The Economy Extension integrates with multiple data providers through the provider-fetcher pattern. Each provider implements specific fetchers for different economic data models.
The Federal Reserve Economic Data (FRED) provider offers over 816,000 economic time series. It implements 40+ fetchers registered in openbb_platform/providers/fred/openbb_fred/__init__.py58-105:
Key FRED Fetchers:
FREDConsumerPriceIndexFetcher - CPI data for multiple countriesFredSeriesFetcher - Generic FRED series data by symbolFredSearchFetcher - Search FRED series and releasesFredRegionalDataFetcher - Regional economic data (Geo Fred)FredBalanceOfPaymentsFetcher - Balance of payments dataFredRetailPricesFetcher - Retail prices for common itemsFredUofMichiganFetcher - University of Michigan Consumer SurveyFredSeniorLoanOfficerSurveyFetcher - SLOOS dataFredNonFarmPayrollsFetcher - Employment dataFredPersonalConsumptionExpendituresFetcher - PCE dataFredReleaseTableFetcher - Economic release tablesSources: openbb_platform/providers/fred/openbb_fred/__init__.py1-106 openbb_platform/providers/fred/tests/test_fred_fetchers.py1-532
The OECD provider accesses economic data for OECD member and non-member countries. It implements 9 fetchers registered in openbb_platform/providers/oecd/openbb_oecd/__init__.py16-33:
OECD Fetchers:
OECDCPIFetcher - Consumer Price Index dataOECDGdpNominalFetcher - Nominal GDP dataOECDGdpRealFetcher - Real GDP dataOECDGdpForecastFetcher - GDP forecastsOECDUnemploymentFetcher - Unemployment ratesOECDCompositeLeadingIndicatorFetcher - CLI dataOECDSharePriceIndexFetcher - Share price indicesOECDHousePriceIndexFetcher - House price indicesOecdCountryInterestRatesFetcher - Interest rates by countryThe OECD provider uses country code mappings defined in openbb_platform/providers/oecd/openbb_oecd/utils/constants.py1-685 to standardize country names.
Sources: openbb_platform/providers/oecd/openbb_oecd/__init__.py1-34 openbb_platform/providers/oecd/tests/test_oecd_fetchers.py1-158
The EconDB provider offers official statistics and alternative data sources. It implements 8 fetchers in openbb_platform/providers/econdb/openbb_econdb/__init__.py13-36:
EconDB Fetchers:
EconDbAvailableIndicatorsFetcher - List available indicatorsEconDbCountryProfileFetcher - Country economic profilesEconDbEconomicIndicatorsFetcher - General economic indicatorsEconDbExportDestinationsFetcher - Top export destinationsEconDbGdpNominalFetcher - Nominal GDP with growth ratesEconDbGdpRealFetcher - Real GDP with growth ratesEconDbPortVolumeFetcher - Shipping port volumesEconDbYieldCurveFetcher - Yield curve dataSources: openbb_platform/providers/econdb/openbb_econdb/__init__.py1-37 openbb_platform/providers/econdb/tests/test_econdb_fetchers.py1-146
The Federal Reserve provider accesses data from the U.S. central bank. It implements 13 fetchers in openbb_platform/providers/federal_reserve/openbb_federal_reserve/__init__.py40-60:
Federal Reserve Fetchers:
FederalReserveCentralBankHoldingsFetcher - Federal Reserve SOMA holdings (Treasury and Agency securities)FederalReserveFederalFundsRateFetcher - Federal funds rate (EFFR)FederalReserveFomcDocumentsFetcher - FOMC documents and materials (minutes, transcripts, statements, etc.)FederalReserveInflationExpectationsFetcher - Survey of Professional Forecasters inflation expectationsFederalReserveMoneyMeasuresFetcher - M1/M2 money supply measures (H.6 Release)FederalReserveOvernightBankFundingRateFetcher - Overnight Bank Funding Rate (OBFR)FederalReservePrimaryDealerFailsFetcher - Primary dealer fails to deliver/receive statisticsFederalReservePrimaryDealerPositioningFetcher - Primary dealer net positions by asset classFederalReserveSOFRFetcher - Secured Overnight Financing Rate (SOFR)FederalReserveSvenssonFetcher - Svensson yield curve model parametersFederalReserveTfpFetcher - Total Factor Productivity (TFP) dataFederalReserveTreasuryRatesFetcher - Treasury rates across maturitiesFederalReserveYieldCurveFetcher - Treasury yield curve dataThe Federal Reserve provider includes specialized infrastructure for FOMC documents, with utilities at openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/fomc_documents.py1-250 for fetching and parsing documents from the Federal Reserve website. Historical documents are cached in openbb_platform/providers/federal_reserve/openbb_federal_reserve/assets/historical_releases.json1-10
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/__init__.py1-61 openbb_platform/providers/federal_reserve/tests/test_federal_reserve_fetchers.py1-201 openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/fomc_documents.py1-250
Additional providers include:
Sources: openbb_platform/extensions/economy/integration/test_economy_python.py1-1252
Commands in the Economy Extension follow the standard OpenBB Platform command execution pattern using the three-stage fetcher lifecycle.
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py69-94
Each provider fetcher implements three methods as shown in this example from the FRED CPI fetcher:
ConsumerPriceIndexData objectsSources: openbb_platform/providers/fred/tests/test_fred_fetchers.py78-84 openbb_platform/providers/oecd/tests/test_oecd_fetchers.py36-45
The Economy Extension provides commands organized into categories. Each command is implemented as a decorated async function in the router files.
Commands defined in openbb_platform/extensions/economy/openbb_economy/economy_router.py:
| Command | Model | Description | Line Reference |
|---|---|---|---|
calendar() | EconomicCalendar | Upcoming/historical economic events | 39-66 |
cpi() | ConsumerPriceIndex | Consumer Price Index data | 69-94 |
risk_premium() | RiskPremium | Market risk premium by country | 97-108 |
balance_of_payments() | BalanceOfPayments | Balance of payments reports | 111-131 |
fred_search() | FredSearch | Search FRED series/releases | 134-146 |
fred_series() | FredSeries | Get FRED series data by symbol | 149-170 |
fred_release_table() | FredReleaseTable | FRED economic release tables | 173-197 |
money_measures() | MoneyMeasures | M1/M2 money supply | 200-217 |
unemployment() | Unemployment | Global unemployment data | 220-245 |
composite_leading_indicator() | CompositeLeadingIndicator | CLI data | 248-268 |
fred_regional() | FredRegional | Regional economic data | 271-299 |
country_profile() | CountryProfile | Country statistics profile | 302-324 |
available_indicators() | AvailableIndicators | List available indicators | 327-340 |
indicators() | EconomicIndicators | General economic indicators | 343-410 |
central_bank_holdings() | CentralBankHoldings | Central bank balance sheet | 413-442 |
share_price_index() | SharePriceIndex | Share price indices | 445-466 |
house_price_index() | HousePriceIndex | House price indices | 469-490 |
interest_rates() | CountryInterestRates | Interest rates by country | 493-528 |
retail_prices() | RetailPrices | Retail prices for items | 531-560 |
primary_dealer_positioning() | PrimaryDealerPositioning | Dealer positioning stats | 563-582 |
pce() | PersonalConsumptionExpenditures | PCE reports | 585-606 |
export_destinations() | ExportDestinations | Top export destinations | 609-622 |
primary_dealer_fails() | PrimaryDealerFails | Dealer fails statistics | 625-655 |
direction_of_trade() | DirectionOfTrade | Trade statistics from IMF | 658-692 |
fomc_documents() | FomcDocuments | FOMC documents by year/type | 682-713 |
total_factor_productivity() | TotalFactorProductivity | TFP data from San Francisco Fed | 716-748 |
Sources: openbb_platform/extensions/economy/openbb_economy/economy_router.py39-795
Commands defined in openbb_platform/extensions/economy/openbb_economy/gdp/gdp_router.py:
| Command | Model | Description | Line Reference |
|---|---|---|---|
gdp.forecast() | GdpForecast | Forecasted GDP data | 19-40 |
gdp.nominal() | GdpNominal | Nominal GDP data | 43-64 |
gdp.real() | GdpReal | Real (inflation-adjusted) GDP | 67-83 |
Sources: openbb_platform/extensions/economy/openbb_economy/gdp/gdp_router.py19-84
Commands defined in openbb_platform/extensions/economy/openbb_economy/survey/survey_router.py14-215:
| Command | Model | Description | Line Reference |
|---|---|---|---|
survey.bls_series() | BlsSeries | BLS time series data by series ID | 19-32 |
survey.bls_search() | BlsSearch | Search BLS surveys by category/keyword | 35-61 |
survey.sloos() | SeniorLoanOfficerSurvey | Senior Loan Officer Opinion Survey | 64-78 |
survey.university_of_michigan() | UniversityOfMichigan | U of Michigan Consumer Sentiment | 81-94 |
survey.economic_conditions_chicago() | SurveyOfEconomicConditionsChicago | Chicago Fed Economic Conditions | 97-110 |
survey.manufacturing_outlook_texas() | ManufacturingOutlookTexas | Dallas Fed Manufacturing Survey | 113-133 |
survey.manufacturing_outlook_ny() | ManufacturingOutlookNY | Empire State Manufacturing Survey | 136-176 |
survey.nonfarm_payrolls() | NonFarmPayrolls | Employment situation data | 179-198 |
survey.inflation_expectations() | InflationExpectations | Survey of Professional Forecasters | 201-214 |
Empire State Manufacturing Survey Details:
The NY manufacturing survey (survey.manufacturing_outlook_ny()) is a monthly survey of manufacturers in New York State conducted by the Federal Reserve Bank of New York. The survey tracks changes in various indicators from the previous month and likely direction six months ahead. First report was April 2002, though data dates back to July 2001. About 200 manufacturing executives receive the survey on the first of each month, with ~100 responses received by the tenth.
Sources: openbb_platform/extensions/economy/openbb_economy/survey/survey_router.py1-215 openbb_platform/extensions/economy/integration/test_economy_python.py763-1282
Commands in the shipping sub-router:
shipping.chokepoint_info() - Shipping chokepoint informationshipping.chokepoint_volume() - Volume through chokepointsshipping.port_volume() - Port volume dataSources: openbb_platform/extensions/economy/integration/test_economy_python.py1182-1239
The Economy Extension uses standard models defined in openbb_platform/core/openbb_core/provider/standard_models/ Each command's model parameter in the @router.command() decorator specifies which standard model to use.
Key Standard Models:
GdpNominal - openbb_platform/core/openbb_core/provider/standard_models/gdp_nominal.pyGdpForecast - openbb_platform/core/openbb_core/provider/standard_models/gdp_forecast.py1-33GdpReal - openbb_platform/core/openbb_core/provider/standard_models/gdp_real.py1-35ConsumerPriceIndex - Consumer price index dataUnemployment - Unemployment statisticsPrimaryDealerFails - openbb_platform/core/openbb_core/provider/standard_models/primary_dealer_fails.py1-32Sources: openbb_platform/core/openbb_core/provider/standard_models/gdp_nominal.py openbb_platform/core/openbb_core/provider/standard_models/gdp_forecast.py1-33 openbb_platform/core/openbb_core/provider/standard_models/gdp_real.py1-35 openbb_platform/core/openbb_core/provider/standard_models/primary_dealer_fails.py1-32
Each provider can extend the standard models with additional fields. For example, the EconDB GDP nominal fetcher adds growth rate fields:
EconDbGdpNominalData (extends GdpNominalData):
nominal_growth_qoq - Quarter-over-quarter growth ratenominal_growth_yoy - Year-over-year growth ratevalue - Nominal GDP valueOECDGdpNominalData (extends GdpNominalData):
Sources: openbb_platform/providers/econdb/openbb_econdb/models/gdp_nominal.py81-96 openbb_platform/providers/oecd/openbb_oecd/models/gdp_nominal.py90-92
The Federal Reserve provider includes a comprehensive system for accessing FOMC (Federal Open Market Committee) documents. This system provides access to historical and current monetary policy materials.
The system supports filtering by document type using the FomcDocumentType literal defined at openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/fomc_documents.py8-24:
| Document Type | Description |
|---|---|
all | All document types |
monetary_policy | Monetary policy statements |
minutes | Meeting minutes |
projections | Economic projections (Summary of Economic Projections) |
materials | Meeting materials |
press_release | Press releases |
press_conference | Press conference transcripts |
agenda | Meeting agendas |
transcript | Full meeting transcripts |
speaker_key | Speaker identification keys for transcripts |
beige_book | Beige Book (regional economic summaries) |
teal_book | Teal Book (staff economic forecasts - historical) |
green_book | Green Book (staff economic analysis - historical) |
blue_book | Blue Book (monetary policy alternatives - historical) |
red_book | Red Book (foreign economic analysis - historical) |
The FederalReserveFomcDocumentsData model at openbb_platform/providers/federal_reserve/openbb_federal_reserve/models/fomc_documents.py86-132 includes:
date - Document date (YYYY-MM-DD format)doc_type - Type of FOMC documentdoc_format - Format (pdf, htm)url - Full URL to the documentThe model includes custom widget configuration for multi-file viewing in the OpenBB Workspace interface, with integration to a document download endpoint at /federal_reserve/fomc_documents_download.
Historical FOMC documents (1959-2024) are cached in JSON format at openbb_platform/providers/federal_reserve/openbb_federal_reserve/assets/historical_releases.json1-10 The cache is loaded using load_historical_fomc_documents() with LRU caching to avoid repeated file reads.
Current documents are fetched dynamically from the Federal Reserve website using get_current_fomc_documents() at openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/fomc_documents.py46-128 with TTL caching (1 hour) to reduce HTTP requests.
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/models/fomc_documents.py1-173 openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/fomc_documents.py1-250 openbb_platform/providers/federal_reserve/openbb_federal_reserve/assets/historical_releases.json1-10
The Federal Reserve provider includes specialized infrastructure for primary dealer positioning and fails statistics from the New York Fed.
Categories are mapped to specific NY Fed series IDs at openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/primary_dealer_statistics.py68-129 The POSITION_GROUPS_TO_SERIES dictionary maps user-friendly category names to lists of series identifiers:
Available Categories:
treasuries - All Treasury securities (bills, notes, bonds, TIPS)bills - Treasury bills onlycoupons - Treasury coupons across all maturitiesnotes - Treasury notes by maturity rangestips - Treasury Inflation-Protected Securitiesmbs - All mortgage-backed securitiescmbs - Commercial mortgage-backed securitiesmunicipal - State and municipal government obligationscorporate - Corporate securities (all)commercial_paper - Commercial papercorporate_ig - Investment grade corporate bondscorporate_junk - High-yield corporate bondsabs - Asset-backed securitiesEach category can contain multiple series IDs representing different maturity ranges or security types. For example, the coupons category includes series for different maturity buckets (≤2Y, 2-3Y, 3-6Y, etc.).
Primary dealer fails data tracks fails to deliver (FTD) and fails to receive (FTR) for different asset classes. The data is sourced from the NY Fed's weekly H.15 statistical release. Series titles are mapped at openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/primary_dealer_statistics.py6-27
The PrimaryDealerFailsData model at openbb_platform/core/openbb_core/provider/standard_models/primary_dealer_fails.py27-31 includes:
date - Report datesymbol - NY Fed series identifierProvider implementations add fields like value for the fail amount in millions of dollars and descriptive fields like name and title.
Sources: openbb_platform/providers/federal_reserve/openbb_federal_reserve/models/primary_dealer_positioning.py1-161 openbb_platform/providers/federal_reserve/openbb_federal_reserve/utils/primary_dealer_statistics.py1-172 openbb_platform/core/openbb_core/provider/standard_models/primary_dealer_fails.py1-32
Sources: openbb_platform/extensions/economy/integration/test_economy_python.py151-218
Sources: openbb_platform/extensions/economy/integration/test_economy_python.py62-108
Sources: openbb_platform/extensions/economy/integration/test_economy_python.py269-372
Sources: openbb_platform/extensions/economy/integration/test_economy_python.py763-921
Sources: openbb_platform/extensions/economy/integration/test_economy_python.py638-1260 openbb_platform/providers/federal_reserve/tests/test_federal_reserve_fetchers.py168-188
Many endpoints require country codes or names. The API typically accepts both full country names in snake_case format (e.g., united_states) or standard ISO country codes. The providers maintain mappings between country names and codes.
Some endpoints (like those from OECD or IMF) also support special country groupings like all, G7, G20, or euro_area.
Sources: openbb_platform/providers/oecd/openbb_oecd/utils/constants.py openbb_platform/providers/imf/openbb_imf/assets/imf_country_map.json openbb_platform/providers/imf/openbb_imf/utils/irfcl_helpers.py
Many endpoints support options for data frequency, units, and transformations:
annual / a - Annual dataquarter / q - Quarterly datamonthly / m - Monthly dataweekly / w - Weekly datadaily / d - Daily datayoy - Year-over-year changeqoq - Quarter-over-quarter changemom - Month-over-month changeperiod - Period-to-period changeindex - Indexed values (base period = 100)chg - Changepch - Percent changeSources: openbb_platform/assets/reference.json openbb_platform/providers/fred/openbb_fred/__init__.py
The Economy Extension includes comprehensive integration tests for both Python and API interfaces. Tests are organized by provider and command.
The integration tests at openbb_platform/extensions/economy/integration/test_economy_python.py1-1282 cover:
calendar(), cpi(), balance_of_payments())Each test function uses @pytest.mark.parametrize to test multiple provider configurations and parameter combinations. Tests validate that:
OBBject instancelen(result.results) > 0)Sources: openbb_platform/extensions/economy/integration/test_economy_python.py1-1282 openbb_platform/extensions/economy/integration/test_economy_api.py1-1250 openbb_platform/extensions/tests/test_integration_tests_python.py1-78
The Economy API implements consistent error handling across all endpoints:
All errors and warnings are included in the returned OBBject when applicable.
Sources: openbb_platform/providers/oecd/openbb_oecd/models/gdp_nominal.py openbb_platform/providers/imf/openbb_imf/models/economic_indicators.py
Refresh this wiki