Worldbank Api

World Bank Indicators API

The World Bank Indicators API exposes ~30,000 time-series indicators for 217 economies and 78 regional/income aggregates, some series back to 1960. No API key, no signup, no documented rate limit — plain HTTPS GET.

Base URL: https://api.worldbank.org/v2

Always append format=json — the default response format is XML.

Fastest path: bundled script

For the common case — one or more indicators for one or more countries — run the bundled zero-dependency script (Python 3.8+, stdlib only):

python3 scripts/wb_data.py gdp US,JP,CN                    # alias + ISO codes, last 5 years
python3 scripts/wb_data.py SP.POP.TOTL BR --date 2000:2024 # explicit indicator code + range
python3 scripts/wb_data.py inflation all --mrv 1           # every economy, latest value
python3 scripts/wb_data.py population WLD,EUU --json       # aggregates, raw JSON output
python3 scripts/wb_data.py --search "renewable energy"     # find indicator codes by keyword
python3 scripts/wb_data.py --aliases                       # list built-in indicator aliases

Exit codes: 0 success, 1 not found / no data, 2 API or network error.

Call the API directly (below) for anything else: country metadata, indicator discovery by topic/source, monthly/quarterly series, or non-Python environments.

Core data query

GET https://api.worldbank.org/v2/country/{codes}/indicator/{indicator}?format=json

• {codes} — ISO-2 or ISO-3 country codes, semicolon-separated (US;JP;CN),

an aggregate code (WLD, EUU, HIC...), or all (all 265 economies+aggregates).

• {indicator} — an indicator code like NY.GDP.MKTP.CD (case-insensitive).

Example

GET https://api.worldbank.org/v2/country/US;JP/indicator/NY.GDP.MKTP.CD?format=json&mrv=2

[
  {"page": 1, "pages": 1, "per_page": 50, "total": 4,
   "sourceid": "2", "lastupdated": "2026-07-01"},
  [
    {"indicator": {"id": "NY.GDP.MKTP.CD", "value": "GDP (current US$)"},
     "country": {"id": "US", "value": "United States"},
     "countryiso3code": "USA", "date": "2025",
     "value": 30769700000000, "unit": "", "obs_status": "", "decimal": 0},
    {"...": "one object per country×year, newest first"}
  ]
]

Response shape: a 2-element JSON array — [0] is pagination metadata, [1] is the data array (or null when nothing matched). value is null for years a country hasn't reported. Rows are sorted newest-first per country.

Time and pagination parameters

| Parameter | Meaning | |---|---| | date=2020 / date=2000:2024 | Single year or range. Monthly 2025M01:2025M06, quarterly 2024Q1:2025Q4 for the few monthly/quarterly sources. | | mrv=N | Most recent N values per country (overrides date) | | mrnev=N | Most recent N non-empty values — use for "latest available" since many series lag 1–2 years | | gapfill=Y | With mrv: forward-fill missing years with the last known value | | per_page=N (default 50) | Rows per page; large values (e.g. 20000) work fine — set it high to avoid paging | | page=N | Page number; loop while `page list[dict]: """Fetch a World Bank series; returns a flat list of data points.""" url = f"https://api.worldbank.org/v2/country/{countries}/indicator/{indicator}" r = requests.get(url, params={"format": "json", "perpage": 20000, **params}, timeout=30) r.raisefor_status() body = r.json() if "message" in body[0]: # API errors come back as HTTP 200 raise ValueError(body[0]["message"][0]["value"]) return body[1] or []

gdp = wbseries("NY.GDP.MKTP.CD", "US;JP;CN", date="2015:2024") latest = wbseries("SP.DYN.LE00.IN", "all", mrnev=1)

```javascript
const url = "https://api.worldbank.org/v2/country/US;JP/indicator/NY.GDP.MKTP.CD"
          + "?format=json&mrv=5&per_page=1000";
const [meta, rows] = await (await fetch(url)).json();
if (meta.message) throw new Error(meta.message[0].value);
for (const r of rows ?? []) console.log(r.country.value, r.date, r.value);

Errors

Errors come back as HTTP 200 with a message envelope — always check for it:

[{"message": [{"id": "120", "key": "Invalid value",
               "value": "The provided parameter value is not valid"}]}]

• 120 — invalid country or indicator code (also returned for economies the

World Bank doesn't cover, e.g. Taiwan has no data under any code).

• 175 — indicator exists but its data was deleted or archived (e.g. the

old CO2 series EN.ATM.CO2E.PC → use the EN.GHG.* replacements; the whole Doing Business source is archived). Search for a successor code.

• Occasional transient HTML "Request Error" pages instead of JSON — retry

once before treating it as a failure.

Practical tips

• Prefer mrnev=1 over mrv=1 for "the latest number" — most series lag one

to two years, so mrv=1 often returns the newest year with value: null.

• Set per_page high (e.g. 20000) and you'll almost never need to paginate;

all countries × one year is only 265 rows.

• total in the metadata counts country×period slots, including null values.
• Localized names: insert a language code after /v2 —

/v2/zh/country/CN/indicator/... (supported: en, es, fr, ar, zh). Only labels are translated; codes and values are identical.

• Data revisions land monthly-ish; lastupdated in the metadata tells you the

source's refresh date.

• Yearly is the norm. Monthly/quarterly exists only in a few sources (Global

Economic Monitor source=15, quarterly debt source=20/22/23) — see references/endpoints.md.

For the full endpoint catalog (indicators list, topics, sources, regions, income levels, lending types, languages, monthly/quarterly data) read references/endpoints.md; for ~100 more verified indicator codes by topic read references/indicators.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NanookAI
• Source: NanookAI/worldbank-api
• License: MIT

Install and usage instructions live in the source repository linked above.