macroeconomics
Retrieve macroeconomic indicators by country—GDP, inflation, trade balance, exchange rates, and crisis signals—to analyze economic conditions over custom date ranges.
Instructions
Macroeconomic indicators by country (GDP, real GDP, CPI, PPI, inflation rate, trade balance, imports, exports, investment, consumption, business/consumer confidence, house prices, rent prices, exchange rates, real effective exchange rate, money supply, household savings rate, household debt-to-income ratio, output gap, real interest rate, misery index, banking/currency/sovereign debt crisis indicators, commercial real estate prices, commodity forward curves). Requires countries='United States' — use comma-separated values for multiple countries. Do NOT use tickers= for this tool. Supports start_date/end_date. Indicators with a period come at the highest frequency they are published at unless period= says otherwise (daily, else weekly, monthly, quarterly, yearly); house prices, rent prices, the household savings rate and the household debt-to-income ratio come quarterly from the OECD (quarterly=false for yearly); the others are yearly. quarterly=true returns quarterly data only where a source has it (a note says when it does not). Supports rolling=N (moving-average smoothing) and trailing=N (trailing N-period sum, e.g. a trailing-4-quarter sum) on the raw series. get_gross_domestic_product_growth returns the latest quarterly real GDP growth (quarter on quarter, or year_over_year=true) without an API key. get_shiller_stock_market_data returns Robert Shiller's monthly US stock market data from 1871 (price, dividend, earnings, CPI, long rate, CAPE; no countries needed). get_exchange_rates returns each country's currency per US dollar (e.g. countries='Japan' for yen per dollar, not a currency pair; for a pair such as EURUSD use the market_data tool with tickers='EURUSD'), defaults to daily rates and accepts end_of_period=true for month-, quarter- or year-end rates (BIS, no key). get_commercial_real_estate_prices covers around twenty economies (BIS, no key). get_inflation_rate and get_consumer_price_index default to monthly data (period='yearly' for annual), without an API key (Eurostat incl. the euro area flash estimate, the ONS for the United Kingdom, the Statistics Bureau of Japan, and the BIS for around sixty other countries incl. the United States, China, India and Brazil). get_consumer_price_index also accepts oecd_source=true for monthly/quarterly OECD data only. get_commodity_forward_curve requires a commodity= argument instead of countries= (e.g. 'Crude Oil', 'Gold') and returns dated futures contracts, not a country series. Also includes six US-only indicators that only return a 'United States' column regardless of the countries= argument: get_industrial_production_index (Federal Reserve G.17) and get_recession_indicator (NBER business cycle dates) work without an API key, while get_retail_sales, get_housing_starts, get_real_personal_income and get_commercial_real_estate_prices require a free FRED API key (optional; get one at https://fred.stlouisfed.org/docs/api/api_key.html). get_economic_calendar returns scheduled economic data releases (event, previous, estimate, actual, impact) rather than a country series. By default it returns only High impact releases from the past 23 days to the coming 7 days; narrow it with countries= (e.g. 'United States') and currencies= (e.g. 'USD,EUR'), filter on event names with events= (e.g. events='PMI' for the purchasing managers' indices with consensus, or 'CPI,Unemployment'), pass impact='Medium' or 'High,Medium' for more, impact='All' for every release, and start_date/end_date for another window (keep it to a few weeks: one month of every country is over 2,000 releases). Its Unit column gives each release's unit; releases quoted in percent and its Change % column are decimals like the rest. Every rate and ratio this tool returns is a decimal fraction, not a percentage: an inflation rate of 4.1% comes back as 0.0412 and a debt-to-GDP ratio of 131.7% as 1.3173. Multiply by 100 before presenting them as percentages. Global Macro Database options: usd=true returns GDP, GDP per capita, consumption, investment, fixed investment, exports, imports, trade balance and current account in millions of US dollars (comparable across countries); get_total_consumption and get_total_consumption_to_gdp_ratio accept component='total', 'household' or 'government'; get_house_prices with inflation_adjusted=true returns real house prices. Yearly GMDB series end at the last observation; pass gmdb_forecasts=true to include the IMF projections up to five years ahead. get_implied_volatility returns volatility indices by market and maturity as decimals, no countries needed (markets='US Equity' VIX 9D-1Y from 1990, 'Euro Area Equity' VSTOXX 1M-24M from 1999, 'Emerging Markets Equity', 'US Equity Volatility' VVIX, 'US Treasury Bonds' VXTLT, 'Crude Oil', 'Gold'; with an FMP key also 'US Treasury Rates' MOVE and 'Japan Government Bonds'), period='daily', 'weekly' or 'monthly'. get_stress_test_scenario returns regulators' stress test scenarios (authority='federal_reserve' quarterly US and international variables incl. Treasury and BBB yields, equity, house prices and VIX; authority='esrb' the EBA bank stress test, yearly, every EU country plus iTraxx spreads), scenario='baseline', 'adverse' or 'historic' (Fed history from 1976), countries= optional; the scenario path is not cut to start_date/end_date. Long-horizon data: get_long_run_asset_returns returns yearly total returns 1870-2020 for 18 advanced economies (Jordà-Schularick-Taylor; asset_class='equity'|'housing'|'bonds'|'bills'|'risky'|'safe'|'wealth', real=true for real returns; licensed for non-commercial use only, so it requires accept_licence=true; countries= optional). get_millennium_of_macroeconomic_data returns the Bank of England's annual UK series from as early as 1086 to 2016 (series= e.g. 'Bank Rate,Consols,Share prices'; set start_date far back, e.g. 1700-01-01). get_scenario_set returns De Nederlandsche Bank's pension scenario set (20,000 scenarios over 100 years, measure='real_world' or 'market_consistent'): quantiles per horizon year of nominal zero rates 1Y-30Y, the euro area 10Y real rate, equity returns and EU/NL inflation; the first call takes one to two minutes. get_asset_class_proxies returns daily total returns of listed funds tracking private equity, infrastructure, hedge funds, merger arbitrage, private credit, real estate and investment grade and high yield credit (asset_classes=, period='daily'|'weekly'|'monthly').
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lag | No | Number of periods to lag when computing growth rates. | |
| usd | No | Return levels in millions of US dollars instead of national currency when True, which makes them comparable across countries (Global Macro Database). | |
| real | No | Whether to deflate the returns by consumer price inflation. | |
| year | No | The year of the Federal Reserve's stress test, from 2025. | |
| limit | No | The rows to return, like head and tail: 5 for the first five, -5 for the last five (the most recent of a time series). A table with its periods as columns (financial statements, ratios) keeps its first or last periods instead. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length. | |
| events | No | Parts of event names to keep, matched without regard to case, e.g. "PMI" for every purchasing managers' index or ["CPI", "Unemployment"]. | |
| growth | No | Return period-over-period growth rates instead of absolute values. | |
| impact | No | The market impact to keep: "Low", "Medium" and/or "High", or "All" for every release. Leave unset to use the default of the indicator you selected. Defaults are 'High' for get_economic_calendar. | |
| period | No | Observation frequency, e.g. 'daily', 'weekly', 'monthly', 'quarterly', or 'annual' (supported values differ per method). Leave unset to use the default of the indicator you selected. Defaults are None for get_consumer_price_index, get_exchange_rates, get_inflation_rate, get_producer_price_index, get_share_prices; 'daily' for get_asset_class_proxies, get_implied_volatility. | |
| series | No | Analyze the indicators of other tools instead of the tickers' prices: references separated by ';', each tool:indicator:tickers-or-countries with an optional :column, e.g. 'valuation:get_price_to_earnings_ratio:AAPL,MSFT; macroeconomics:get_inflation_rate:United States' or 'rates:get_government_bond_yield_curve:United States,Germany:10Y'. Every ticker or country becomes a series named after it, which dependent_ticker and independent_tickers then name. Use start_date for a long enough history. | |
| markets | No | The markets to retrieve, from "US Equity", "Euro Area Equity", "Emerging Markets Equity", "US Equity Volatility", "US Treasury Bonds", "Crude Oil", "Gold", "US Treasury Rates" and "Japan Government Bonds". | |
| measure | No | Sub-measure selector, e.g. 'M1', 'M2', or 'M3' for money supply. Leave unset to use the default of the indicator you selected. Defaults are None for get_money_supply; 'real_world' for get_scenario_set. | |
| returns | No | Whether to return the total return per period instead of the dividend-adjusted price. | |
| rolling | No | Rolling window size in number of periods. When set, the metric is computed over a smoothly overlapping trailing window across the full history (e.g. period='monthly' and rolling=6 gives a rolling 6-month value) instead of one value per period, or (for economics indicators) a simple moving average used to smooth the raw series. | |
| end_date | No | End of the date range in YYYY-MM-DD format. | 2026-10-27 |
| scenario | No | "baseline", "adverse" (the Federal Reserve's severely adverse scenario) or "historic". | adverse |
| trailing | No | Trailing window size in number of periods. Sums the raw values over the trailing N periods (e.g. trailing=4 on quarterly data gives a trailing-4-quarter / TTM-style sum) instead of returning one value per period. | |
| authority | No | For get_stress_test_scenario: "federal_reserve" or "esrb". For get_scenario_set: The regulator: "dnb". Leave unset to use the default of the indicator you selected. Defaults are 'dnb' for get_scenario_set; 'federal_reserve' for get_stress_test_scenario. | |
| commodity | No | The commodity to retrieve the curve for. One of "Crude Oil", "Natural Gas", "Gold", "Silver", "Copper", "Corn", "Wheat" or "Soybeans". Leave unset to use the default of the indicator you selected. Required by: get_commodity_forward_curve. | |
| component | No | Part of final consumption: 'total', 'household' or 'government'. | total |
| contracts | No | The number of contracts to return, the nearest listed ones from the current month on. | |
| countries | No | Country names, comma-separated or as a list, e.g. 'United States,Germany,Japan'. | |
| indicator | Yes | Name of the specific metric to calculate, one of the listed values. Required — search_metrics finds the indicator (and its tool) for a metric by name. | |
| quantiles | No | The quantiles of the distribution per year. | |
| quarterly | No | Return quarterly data instead of annual when True. | |
| rate_type | No | Which nominal interest rate to use. Can be 'long_term' (10-year government bond yield) or 'short_term' (3-month money market rate). | long_term |
| scenarios | No | Whether to return every scenario instead of the distribution. | |
| variables | No | The variables to include, from "Nominal rate 1Y", "Nominal rate 5Y", "Nominal rate 10Y", "Nominal rate 20Y", "Nominal rate 30Y", "Real rate EU 10Y", "Equity return", "Inflation EU" and "Inflation NL". | |
| currencies | No | The currencies to keep, e.g. "USD" or ["USD", "EUR"]. | |
| start_date | No | Start of the date range in YYYY-MM-DD format. | 2021-10-28 |
| asset_class | No | "equity", "housing", "bonds", "bills", "risky", "safe" or "wealth". | equity |
| gmdb_source | No | Use the Global Macro Database as the data source when True, rather than the OECD. The two are independent providers with different country and period coverage; both return rates and ratios as decimal fractions. | |
| oecd_source | No | Whether to get the data from the OECD instead of the Global Macro Database (GMDB). | |
| standardize | No | Return the Z-Score (standard score) instead of the raw values, i.e. how many standard deviations each value is from the mean of its own series. When combined with growth=True, the growth values are standardized instead of the raw values. | |
| show_columns | No | Comma-separated names to filter the output. For historical data use the key names visible in any response record (e.g. 'Close,Volume,Return'). For financial statements use the 'metric' field values from the response (e.g. 'Revenue,Net Income,EBITDA'). Call the tool once without this parameter to see all available names, then repeat with show_columns to reduce response size and token usage. | |
| asset_classes | No | The asset classes to include, from "Private Equity", "Infrastructure", "Hedge Funds", "Merger Arbitrage", "Private Credit", "Real Estate", "Investment Grade Credit" and "High Yield Credit". | |
| end_of_period | No | Whether to return the rate at the end of each month, quarter or year instead of its average. | |
| accept_licence | No | Confirms that the data is used for non-commercial purposes, as its licence (CC BY-NC-SA 4.0) requires. | |
| gmdb_forecasts | No | Set to true to include the years the Global Macro Database projects (IMF World Economic Outlook, up to five years ahead); by default a yearly series ends with its last observation. | |
| year_over_year | No | Whether to return the change on the same quarter a year earlier instead of on the previous quarter. | |
| inflation_adjusted | No | Adjust nominal values for inflation when True. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |