Documentation

Everything you need to integrate macroeconomic data into your applications and AI agents.

Quickstart

Get macroeconomic data in your AI agent or app in 5 minutes.

1Get an API Key

2Connect via MCP (Claude Desktop)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "meridian": {
      "url": "https://api.meridianapi.io/sse"
    }
  }
}

Restart Claude Desktop. You'll see Meridian in your available tools.

3Try It

Ask Claude:

"How's the US economy doing right now?"
"What happened to inflation in the last 3 months?"
"Compare current conditions to 2008"

4Or Use the REST API

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.meridianapi.io/v1/snapshot

Interfaces

Four ways to access Meridian data — pick whatever fits your stack.

🤖

MCP Tools

For AI agents — Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

🌐

REST API

Standard HTTP endpoints for any language or framework. JSON responses.

🐍

Python SDK

pip install meridian-data — Pythonic wrapper with pandas support.

📦

TypeScript SDK

npm install @meridian/sdk — Fully typed, tree-shakeable.

MCP Tools Reference

`get_macro_snapshot`

Returns current values of key macro indicators with historical context.

Parameter	Type	Default	Description
indicators	string[]	Core 6	FRED series IDs
as_of_date	string	today	Point-in-time date
include_history	boolean	false	Include trailing data
history_periods	number	12	Periods of history

Example response:

{
  "snapshot_date": "2026-03-09",
  "regime": {
    "label": "expansion",
    "confidence": 0.7,
    "signals": ["Strong growth", "Normal yield curve"]
  },
  "indicators": [
    {
      "id": "UNRATE",
      "title": "Unemployment Rate",
      "latest": { "date": "2026-02-01", "value": 4.4, "units": "Percent" },
      "changes": { "yoy": 4.76 },
      "context": {
        "percentile_10y": 66.4,
        "z_score_10y": -0.1,
        "direction": "rising"
      }
    }
  ]
}

`explain_macro_change`

Analyzes what changed in a specific indicator.

Parameter	Type	Default	Description
indicator	string	required	FRED series ID
period	string	"1m"	1m, 3m, 6m, 1y, ytd

`compare_macro_regimes`

Compares current conditions to historical periods.

Parameter	Type	Default	Description
compare_to	string[]	auto	Dates or named regimes
indicators	string[]	Core 5	Indicators to compare

Named regimes: 2008_crisis, 2020_covid, 1970s_stagflation, 2001_dotcom, 1990s_expansion, volcker_era

REST API Reference

Base URL: https://api.meridianapi.io

GET/v1/snapshot

Get current macro indicator values with historical context. Same data as the get_macro_snapshot MCP tool.

🔐 Bearer token required

Parameters

indicators·string—Comma-separated series IDs (e.g. UNRATE,CPIAUCSL)

as_of_date·string—Point-in-time date (YYYY-MM-DD)

include_history·boolean—Include trailing historical data

curl -H "Authorization: Bearer mrd_xxx" \
  "https://api.meridianapi.io/v1/snapshot?indicators=UNRATE,CPIAUCSL"

GET/v1/explain

Analyze what changed in a specific indicator over a period. Same data as the explain_macro_change MCP tool.

🔐 Bearer token required

Parameters

indicator·string—Series ID (required)

period·string—1m, 3m, 6m, 1y, or ytd

GET/v1/compare

Compare current conditions to historical periods. Same data as the compare_macro_regimes MCP tool.

🔐 Bearer token required

Parameters

compare_to·string—Comma-separated dates or named regimes

indicators·string—Comma-separated series IDs

GET/v1/series

List all available data series with metadata.

🔐 Bearer token required

GET/v1/series/:id

Get details and recent observations for a specific series.

🔐 Bearer token required

Parameters

:id·path—Series ID (e.g. UNRATE, GDP, BTC-USD)

GET/v1/dashboardPublic

Full economy dashboard — regime classification, 8 categories, 33 key indicators with values, percentiles, and direction.

POST/v1/queryPublic

Natural language query — ask a question about the economy in plain English.

Parameters

question·string—Your question (in request body as JSON)

curl -X POST https://api.meridianapi.io/v1/query \
  -H "Content-Type: application/json" \
  -d '{"question": "How is inflation trending?"}'

GET/v1/health/dataPublic

Data quality health check — stale series, out-of-range values, reconciliation status.

Data Coverage

270+ series across 4 sources. ~380,000 observations. Updated daily.

🇺🇸 U.S. Macro (FRED) — 53 series

GDP & Growth

GDPGDPC1A191RL1Q225SBEA

Inflation

CPIAUCSLCPILFESLPCEPIPCEPILFEPPIFISMICH

Employment

UNRATEPAYEMSICSACCSAJTSJOLAWHAETPCES0500000003

Interest Rates

FEDFUNDSDFFDPRIME

Yield Curves

DGS1MODGS3MODGS6MODGS1DGS2DGS5DGS10DGS20DGS30T10Y2YT10Y3MT10YIET5YIE

Housing

MORTGAGE30USHOUSTPERMITCSUSHPINSAMSPUS

Markets

SP500DEXUSEUDTWEXBGSVIXCLS

Commodities

DCOILWTICOGOLDAMGBD228NLBM

Money Supply

M2SLWALCL

Trade & Fiscal

BOPGSTBFYFSDGFDEBTN

Consumer & Production

UMCSENTRSAFSINDPROTCUDGORDER

Credit

DRTSCILMTOTCI

🇪🇺 European Macro (ECB) — 11 series

Inflation

HICPCore HICP

Interest Rates

MRO RateDeposit Facility

Money & Growth

M3GDP GrowthUnemployment

FX & Bonds

EUR/USDEUR/GBPEUR/JPYDE 10Y Yield

🌍 Global Development (World Bank) — 161 series

Development

GDP per capitaLife expectancyPopulation growthCO2 emissions...

Trade & Finance

Trade % GDPFDIRemittancesExternal debt...

📈 Markets (Yahoo Finance) — 46 assets

Stocks (20)

AAPLMSFTGOOGAMZNNVDAMETATSLABRK-BJPMVUNHHDPGMAJNJXOMAVGOCOSTLLYWMT

Crypto (10)

BTC-USDETH-USDSOL-USDBNB-USDXRP-USDADA-USDDOGE-USDDOT-USDAVAX-USDMATIC-USD

ETFs (10)

SPYQQQIWMGLDTLTEFAVWOHYGXLFXLE

Indices (6)

^GSPC^DJI^IXIC^RUT^VIX^TNX

Total: 270+ series · ~380,000 observations · Updated daily from FRED, ECB, World Bank, and Yahoo Finance.

SDKs

🐍 Python

pip install meridian-data

from meridian import Meridian

client = Meridian(api_key="mrd_xxx")

# Get current snapshot
snapshot = client.snapshot(
    indicators=["UNRATE", "CPIAUCSL", "GDP"]
)
print(snapshot.regime)

# Explain a change
explanation = client.explain("CPIAUCSL", period="3m")
print(explanation.summary)

# Natural language query
answer = client.query("How is the labor market?")
print(answer.text)

📦 TypeScript

npm install @meridian/sdk

import { Meridian } from "@meridian/sdk";

const client = new Meridian({ apiKey: "mrd_xxx" });

// Get current snapshot
const snapshot = await client.snapshot({
  indicators: ["UNRATE", "CPIAUCSL", "GDP"],
});
console.log(snapshot.regime);

// Explain a change
const explanation = await client.explain("CPIAUCSL", {
  period: "3m",
});
console.log(explanation.summary);

// Natural language query
const answer = await client.query("How is the labor market?");
console.log(answer.text);

Authentication

API keys start with mrd_ and are passed as Bearer tokens:

Authorization: Bearer mrd_your_api_key_here

✓

Authenticated endpoints

/v1/snapshot, /v1/explain, /v1/compare, /v1/series — require Bearer token

○

Public endpoints

/v1/dashboard, /v1/query, /v1/health/data — no authentication required

Get your API key at /signup. Keys are scoped per project and can be rotated from your dashboard.

Rate Limits

Plan	Requests / month	Price
Free	1,000	$0
Pro	50,000	$49/mo
Enterprise	Unlimited	$299/mo

Rate limit headers are included in every response. If you hit the limit, you'll receive a 429 status with a Retry-After header.

Documentation

Quickstart

1Get an API Key

2Connect via MCP (Claude Desktop)

3Try It

4Or Use the REST API

Interfaces

MCP Tools

REST API

Python SDK

TypeScript SDK

MCP Tools Reference

get_macro_snapshot

explain_macro_change

compare_macro_regimes

REST API Reference

Data Coverage

🇺🇸 U.S. Macro (FRED) — 53 series

GDP & Growth

Inflation

Employment

Interest Rates

Yield Curves

Housing

Markets

Commodities

Money Supply

Trade & Fiscal

Consumer & Production

Credit

🇪🇺 European Macro (ECB) — 11 series

Inflation

Interest Rates

Money & Growth

FX & Bonds

🌍 Global Development (World Bank) — 161 series

Development

Trade & Finance

📈 Markets (Yahoo Finance) — 46 assets

Stocks (20)

Crypto (10)

ETFs (10)

Indices (6)

SDKs

🐍 Python

📦 TypeScript

Authentication

Rate Limits

Ready to get started?

`get_macro_snapshot`

`explain_macro_change`

`compare_macro_regimes`