macroeconomics
Retrieve and compare country-level GDP, inflation, trade, confidence, and debt indicators to assess economic conditions and trends.
Instructions
Macroeconomic indicators by country (GDP, real GDP, CPI, PPI, export and import price indices, 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, credit-to-GDP gap, debt service ratios, credit to GDP by sector, 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); get_real_interest_rate is monthly (period='yearly' for annual), the nominal rate minus inflation with rate_type='long_term' (default), 'short_term' or 'policy' (the central bank rate, incl. 'Euro Area'); 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). 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_supply_chain_pressure_index returns the New York Fed's Global Supply Chain Pressure Index, monthly from 1998, in standard deviations from its average (not a decimal; a 'World' column, 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, about a week behind). For the change of currencies against the dollar up to the latest close, use the market_data tool with tickers quoted in dollars ('EURUSD,GBPUSD,JPYUSD,CNYUSD,CHFUSD') and their Cumulative Return. get_commercial_real_estate_prices covers around twenty economies (BIS). get_credit_to_gdp_gap (the Basel III credit gap), get_debt_service_ratio and get_credit_to_gdp_ratio come quarterly from the BIS, for around 45, 30 and 45 economies; borrowers='private' (default), 'households' or 'corporations' selects the sector (get_credit_to_gdp_ratio also 'government' and 'non_financial'). get_inflation_rate and get_consumer_price_index default to monthly data (period='yearly' for annual) (sources: 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; the US months the BLS has released since the latest BIS update are added, so a CPI release appears the same day). measure='core' (all items less food and energy) or a component, 'energy', 'food', 'goods', 'services' or 'shelter' (US only), returns those monthly for the United States (BLS CPI-U, not seasonally adjusted; about the last three years without a FRED key) and the euro area and European countries (Eurostat HICP). get_consumer_price_index also accepts oecd_source=true for monthly/quarterly OECD data only. get_consumer_price_index with cumulative=true returns the growth of 1 in prices since the first period of the date range (1.346 for prices 34.6% higher). get_purchasing_power returns what 100 at start_date buys in every later month, in start_date prices (100 × CPI(start) / CPI(t), e.g. 74.29 when prices rose 34.6%; period='yearly' for annual averages); overnight_rate=true deposits the 100 at the currency's overnight rate compounded daily (€STR for the Euro Area and its members, SONIA, TONA, SOFR; monthly only), the real value of cash, with countries without an overnight rate left out with a note; each month's cash value is paired with that same month's CPI, so months whose CPI is not yet published are left out. get_producer_price_index, get_export_price_index and get_import_price_index return monthly indices (period='quarterly' or 'yearly' for averages) from the official publishers: Eurostat for the euro area, the EU and around 35 European countries, the BLS for the United States (about the last three years without a FRED key) and the Bank of Japan; growth=true with lag=12 gives the year-on-year change. China has no producer price index there: get_economic_calendar with countries='China' and events='Producer Price' has its monthly year-on-year release. get_commodity_prices returns the World Bank's monthly average prices in US dollars from 1960 (the Pink Sheet, no countries needed): commodity= e.g. 'Gold', 'Crude oil Brent', 'Crude oil WTI', 'Copper', 'Natural gas Europe' (the World Bank's names without commas, about seventy; all when left out), in $/troy oz for precious metals, $/bbl for oil, $/mmbtu for gas and $/mt for base metals and grains; deflate_with='United States' gives real prices in the money of the latest month of that country's CPI up to end_date (e.g. gold in 1980 against today's), and econometrics takes the same with series='macroeconomics:get_commodity_prices:Gold' and deflate_with='United States' (e.g. get_level_significance with level= for the first month above the 1980 peak). get_chokepoint_transits returns IMF PortWatch's daily ship transits through 28 maritime chokepoints from 2019 (no countries needed): chokepoints= e.g. 'Strait of Hormuz,Suez Canal,Bab el-Mandeb Strait,Cape of Good Hope,Panama Canal' (a part such as 'Hormuz' works; all when left out), a column per ship category (Container, Dry Bulk, General Cargo, Ro-Ro, Tanker, Cargo = all but tankers, Total) and per chokepoint when there are several; show_columns='Tanker' keeps one category. measure='transits' (number of ships, default) or 'trade_volume' (estimated cargo in metric tons); period='weekly', 'monthly', 'quarterly' or 'yearly' sums the days (complete periods only). Updated weekly; days are UTC. get_commodity_forward_curve and get_commodity_term_structure take commodity= instead of countries= ('Crude Oil', 'Natural Gas', 'Gold', 'Silver', 'Copper', 'Corn', 'Wheat' or 'Soybeans', comma-separated for several; all eight when left out). get_commodity_forward_curve returns the daily settlement of each dated futures contract listed today (columns are delivery months, e.g. '2026-12'); generic=true returns the generic (nearby) curve as it stood each day instead (Front, +1, ... +11: positions ranked per day, rolling at each contract's last trading day, not interpolated to fixed maturities), and growth=true with lag=N the change of each column over N trading days. get_commodity_term_structure returns per day the front and the far contract (the last of the 12-month strip starting with the front, e.g. Dec26 against Nov27), their prices, the Spread (front minus far, positive in backwardation), the Slope (far / front - 1, a decimal), the annualised Roll Yield (ln(front / far) x 12 / months, a decimal) and Structure ('Backwardation', 'Contango' or 'Flat'); its time series gives the widest spread directly. Yahoo Finance drops a contract once it expires, so on a past date the positions (and the term structure) whose contract has expired since are empty; generic=false on get_commodity_term_structure compares today's front and far contract over their full history instead. Also includes five US-only indicators that only return a 'United States' column regardless of the countries= argument: get_industrial_production_index (Federal Reserve G.17), get_recession_indicator (NBER business cycle dates), get_retail_sales (Census Bureau, monthly from 1992), get_housing_starts (Census Bureau, monthly from 1959) and get_real_personal_income (BEA, monthly from 1959). 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. as_series=true returns the Actual of every event by the period it covers instead of the releases by date (read from the event name: the month, quarter or year; a December figure released in January belongs to the previous year), a column per event and its consensus as ' Estimate', keeping the latest release of a period (the final figure after a flash); the default impact is High, so pass impact='All' to include Medium and Low releases. In the econometrics tool, series='macroeconomics:get_economic_calendar:China:Producer Price Index YoY' reads one such event as a series (the event name without its period as the column), every impact included; a figure published for two months at once, such as China's January and February trade, is kept once under the later month. The calendar starts in 2013 for most countries. Its Currency column is the currency of the market a release concerns, not of its value (China's balance of trade is in US dollars). 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_gross_domestic_product with inflation_adjusted=true returns real GDP (with usd=true in millions of US dollars at constant 2015 prices) and get_house_prices with inflation_adjusted=true 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). deflate_with='United States' puts a money series in today's dollars (the latest year of that country's CPI), e.g. series='$ Oil prices'; growth=true with lag= gives the change over lag years. 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').
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"indicator": "<indicator>"
},
"name": "macroeconomics"
}
}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). | |
| rank | No | true ranks the tickers (or countries) within every period, from the highest value (rank 1) to the lowest, and compares each with its neighbour toward the middle of the ranking: the Difference (in points for returns) and the Multiple (only when both have the same sign), so the first and last rank show how far the best and the worst stand apart, e.g. a fall more than twice as large as the next one. Needs a value per period and ticker; pick one field with show_columns where there are more. | |
| 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, and rows per ticker (an earnings calendar) are selected per ticker. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length. 0 returns every row. | |
| 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_export_price_index, get_import_price_index, get_inflation_rate, get_producer_price_index, get_purchasing_power, get_real_interest_rate, get_share_prices; 'daily' for get_asset_class_proxies, get_chokepoint_transits, 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. | |
| generic | No | For get_commodity_forward_curve: Whether the columns are the positions on each day's curve (Front, +1, +2, ...) instead of the contracts listed today. For get_commodity_term_structure: Whether the front and far contract are those of each day's curve, instead of today's. Leave unset to use the default of the indicator you selected. Defaults are False for get_commodity_forward_curve; True for get_commodity_term_structure. | |
| 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 'all' for get_consumer_price_index, get_inflation_rate; None for get_money_supply; 'real_world' for get_scenario_set; 'transits' for get_chokepoint_transits. | |
| 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; left empty, today (or the indicator's own window). | |
| 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. | |
| as_series | No | Whether to return the Actual and Estimate of every event as time series by the period they cover, with (Country, Event) columns, instead of the releases by date. | |
| 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. | |
| borrowers | No | For get_debt_service_ratio: The borrowing sector: "private" (households and non-financial corporations together), "households" or "corporations" (non-financial corporations). For get_credit_to_gdp_ratio: The borrowing sector: "private" (households and non-financial corporations), "households", "corporations" (non-financial corporations), "government" (at nominal value) or "non_financial" (all three together). | private |
| commodity | No | For get_commodity_forward_curve: The commodity, or a list of them, to retrieve the curve for: "Crude Oil", "Natural Gas", "Gold", "Silver", "Copper", "Corn", "Wheat" or "Soybeans". For get_commodity_prices: The commodities, e.g. "Gold" or ["Gold", "Crude oil Brent"], as named by the World Bank without commas ("Crude oil, Brent" is "Crude oil Brent"), in any casing. For get_commodity_term_structure: The commodity, or a list of. | |
| 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, or with generic the number of positions (the front included). | |
| 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), 'short_term' (3-month money market rate) or 'policy' (central bank policy 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". | |
| cumulative | No | Return the cumulative value compounded over time instead of the discrete value per period. Always rebased to start at 1 at the beginning of the selected date range. | |
| 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; left empty, five years before today (or the indicator's own window). | |
| asset_class | No | "equity", "housing", "bonds", "bills", "risky", "safe" or "wealth". | equity |
| chokepoints | No | The chokepoints, e.g. "Strait of Hormuz" or ["Suez Canal", "Cape of Good Hope"], in any casing; a part of a name that identifies one chokepoint, such as "Hormuz" or "Suez", works too. | |
| 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. | |
| deflate_with | No | With series: the country whose consumer price index the indicators that take deflate_with are deflated with, e.g. 'United States' for 'macroeconomics:get_commodity_prices:Gold' in real terms. | |
| 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. | |
| overnight_rate | No | Whether the 100 earns the overnight rate of its currency instead of being held as banknotes. | |
| 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 |