# World Bank Data API — economic & development indicators (GDP, inflation, population, unemployment) by country and year, multi-country compare, country metadata, indicator search, browse-by-topic and one-call country profiles

> time-series for one+ indicators (code or shortcut) across one+ countries/all; date/mrv/mrnev, rank
> ReefAPI engine `worldbank` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/worldbank/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /worldbank/v1/indicator — 2 credits
time-series for one+ indicators (code or shortcut) across one+ countries/all; date/mrv/mrnev, rank

**Parameters:**
- `country` (string, required) — One or more economy codes, separated by ; , or space, or 'all' for every economy. Accepts: ISO 2-letter ('US', 'TR') or 3-letter ('USA', 'CHN') country codes; pass several for a multi-country compare ('US;CN;DE'). World Bank AGGREGATE codes also work as a 'country' here — e.g. WLD (World), EUU (European Union), EMU (Euro area), and income groups HIC/UMC/LMC/LIC, regions ECS/SAS/SSF — to get region/income-group totals. Discover codes via action=country / reference (kind=regions|income_levels).
- `indicator` (string, required) — One or more World Bank indicator codes OR friendly shortcut aliases (e.g. 'gdp', 'inflation'), separated by ; , or space. Real codes are case-sensitive; shortcut aliases are not. See action=shortcuts.
- `date` (string, optional) — Year or year range (e.g. '2020' or '2015:2022'). Omit for all years; combine with mrv/mrnev for recent-values windows instead.
- `mrv` (integer, optional) — Most-Recent-Values: return only the latest N data points per series.
- `mrnev` (integer, optional) — Most-Recent-Non-Empty-Values: latest N NON-null data points per series.
- `drop_nulls` (boolean, optional, default false) — Drop observations whose value is null from each series.
- `rank` (boolean, optional, default false) — Rank countries by latest value (only when a SINGLE indicator is queried); adds a 'rank' field to each series.
- `per_page` (integer, optional, default 1000) — World Bank API page size for paging through observations.
- `max_pages` (integer, optional, default 10) — Maximum number of observation pages to fetch (caps very large pulls).
- `frequency` (enum, optional) — Data frequency for indicators that publish sub-annual series (most WDI indicators are yearly). [one of: Y, Q, M]
- `gapfill` (boolean, optional, default false) — Carry the last observed value forward to fill gaps (used with mrv).

**Returns:** data[] one series per (indicator,country) with series[].{date,value}, latest_value, observations (+ rank when ranked); indicators[], countries[]

**Example request body:**
```json
{
  "country": "US",
  "indicator": "NY.GDP.MKTP.CD",
  "date": "2015:2022"
}
```

### POST /worldbank/v1/country — 1 credit
country metadata for codes/all or filtered by region/income_level/lending_type

**Parameters:**
- `country` (string, required) — One or more economy codes, separated by ; , or space, or 'all' for every economy. Accepts: ISO 2-letter ('US', 'TR') or 3-letter ('USA', 'CHN') country codes; pass several for a multi-country compare ('US;CN;DE'). World Bank AGGREGATE codes also work as a 'country' here — e.g. WLD (World), EUU (European Union), EMU (Euro area), and income groups HIC/UMC/LMC/LIC, regions ECS/SAS/SSF — to get region/income-group totals. Discover codes via action=country / reference (kind=regions|income_levels).
- `region` (string, optional) — Filter countries by region (matches a region id like 'ECS' or its name); forces an all-countries scan. See reference kind=regions.
- `income_level` (string, optional) — Filter countries by income group (id like 'HIC'/'LIC' or its name); forces an all-countries scan. See reference kind=income_levels.
- `lending_type` (string, optional) — Filter countries by lending type (id like 'IBRD'/'IDA' or its name); forces an all-countries scan. See reference kind=lending_types.
- `exclude_aggregates` (boolean, optional, default false) — Drop World Bank aggregate rows (regions/income groups/WLD) and keep only real economies.
- `all` (boolean, optional, default false) — Return metadata for every economy (equivalent to country='all').

**Returns:** countries[] with region/income_level/lending_type/capital/lat-long, count (+ filters echo when filtered)

**Example request body:**
```json
{
  "country": "US"
}
```

### POST /worldbank/v1/search_indicators — 1 credit
local keyword search over the indicator catalog (WDI default; full=all sources)

**Parameters:**
- `query` (string, required) — Keyword(s) to match against indicator id + name (all terms must match, case-insensitive).
- `source` (string, optional, default "2") — World Bank source/database id to search (default 2 = World Development Indicators). Ignored when full=true.
- `full` (boolean, optional, default false) — Search the FULL cross-source indicator catalog instead of just WDI.
- `topic` (string, optional) — Optional topic filter (matches a topic id or name) layered on top of the keyword search.
- `limit` (integer, optional, default 50) — Maximum number of matching indicators to return.

**Returns:** results[] {id,name,unit,source,topics}, count (total matches), returned, scope

**Example request body:**
```json
{
  "query": "gdp growth"
}
```

### POST /worldbank/v1/indicator_metadata — 1 credit
definition/source/organization/topics for one+ indicator codes/aliases

**Parameters:**
- `indicator` (string, required) — One or more World Bank indicator codes OR friendly shortcut aliases (e.g. 'gdp', 'inflation'), separated by ; , or space. Real codes are case-sensitive; shortcut aliases are not. See action=shortcuts.

**Returns:** indicators[] {id,name,source,source_note,source_organization,topics}, count

**Example request body:**
```json
{
  "indicator": "gdp"
}
```

### POST /worldbank/v1/country_profile — 2 credits
one-call headline snapshot (most-recent ~10 key metrics) for one+ countries

**Parameters:**
- `country` (string, required) — One or more economy codes, separated by ; , or space, or 'all' for every economy. Accepts: ISO 2-letter ('US', 'TR') or 3-letter ('USA', 'CHN') country codes; pass several for a multi-country compare ('US;CN;DE'). World Bank AGGREGATE codes also work as a 'country' here — e.g. WLD (World), EUU (European Union), EMU (Euro area), and income groups HIC/UMC/LMC/LIC, regions ECS/SAS/SSF — to get region/income-group totals. Discover codes via action=country / reference (kind=regions|income_levels).
- `metrics` (string, optional) — Optional comma/semicolon list of shortcut keys or indicator codes to include in the profile. Omit for the default ~10-metric headline set.

**Returns:** profiles[] {country,region,income_level,indicators{metric:{value,date,unit}}}, count, metrics[]

**Example request body:**
```json
{
  "country": "FR"
}
```

### POST /worldbank/v1/shortcuts — 1 credit
list the metric->indicator-code map, or metric=<key>&country=<code> to fetch directly

**Parameters:**
- `metric` (enum, optional) — A friendly metric key to fetch directly. Omit to LIST the full metric→indicator-code map instead. [one of: gdp, gdp_per_capita, gdp_growth, gni_per_capita, inflation, population, population_growth, unemployment, labor_force, life_expectancy, poverty, exports, imports, fdi, exchange_rate, real_interest_rate, gov_debt, co2_per_capita, electricity_access, internet_users, mobile_subs, health_exp_gdp, military_exp_gdp, tax_revenue_gdp, current_account, gross_savings_gdp, agriculture_gdp, industry_gdp, services_gdp, urban_population_pct, trade_gdp]
- `country` (string, optional) — One or more economy codes, separated by ; , or space, or 'all' for every economy. Accepts: ISO 2-letter ('US', 'TR') or 3-letter ('USA', 'CHN') country codes; pass several for a multi-country compare ('US;CN;DE'). World Bank AGGREGATE codes also work as a 'country' here — e.g. WLD (World), EUU (European Union), EMU (Euro area), and income groups HIC/UMC/LMC/LIC, regions ECS/SAS/SSF — to get region/income-group totals. Discover codes via action=country / reference (kind=regions|income_levels).
- `date` (string, optional) — Year or year range (e.g. '2020' or '2015:2022'). Omit for all years; combine with mrv/mrnev for recent-values windows instead.
- `mrv` (integer, optional) — Most-Recent-Values: return only the latest N data points per series.
- `mrnev` (integer, optional) — Most-Recent-Non-Empty-Values: latest N NON-null data points per series.

**Returns:** shortcuts{key:{code,name,unit}} + count when listing; OR the indicator time-series (data[]) when metric=<key>&country=<code>

### POST /worldbank/v1/reference — 1 credit
reference lists: regions | income_levels | lending_types | sources | topics

**Parameters:**
- `kind` (enum, required) — Which reference list to return. [one of: regions, income_levels, lending_types, sources, topics, region, income_level, income, incomelevel, lending_type, lendingtype, lending, source, topic]

**Returns:** kind, items[] (shape depends on kind: regions/income_levels/lending_types/sources/topics), count

**Example request body:**
```json
{
  "kind": "income_levels"
}
```

### POST /worldbank/v1/topic_indicators — 1 credit
browse every indicator in a World Bank topic (Health, Economy, Climate, etc.) by topic id or name; optional keyword filter

**Parameters:**
- `topic` (string, required) — A World Bank topic, as its numeric id ('8') OR its name ('health', 'economy', 'climate'). The 21 topics include Agriculture & Rural Development, Economy & Growth, Education, Energy & Mining, Environment, Financial Sector, Health, Infrastructure, Poverty, Public Sector, Science & Technology, Social Protection & Labor, Trade, Urban Development, Gender, Climate Change. List ids/names via action=reference (kind=topics).
- `query` (string, optional) — Optional keyword(s) to narrow the topic's indicator list locally (all terms must match the indicator id or name, case-insensitive). Omit to list every indicator in the topic.
- `limit` (integer, optional, default 50) — Maximum number of matching indicators to return.
- `per_page` (integer, optional, default 1000) — World Bank API page size for paging through observations.
- `max_pages` (integer, optional, default 10) — Maximum number of observation pages to fetch (caps very large pulls).

**Returns:** topic_id, topic, count (total in topic), returned, results[] {id,name,unit,source,topics}

**Example request body:**
```json
{
  "topic": "health",
  "limit": 25
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=worldbank
- Human docs page: https://reefapi.com/docs/worldbank
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt