World Bank API & Scraper
The World Bank Data API returns economic and development indicators as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary indicator endpoint returns a time series per indicator and country with dated values, a latest value and observation count, and you can pull a country, search indicators, get indicator metadata, a country_profile, topic indicators and reference data. It is built for research, dashboards and data products that need authoritative World Bank indicators without the raw API's paging. One ReefAPI key, one shared credit pool, the standard { ok, data, meta, error } envelope.
Codes you pass in, codes you get back
You can pass a two-letter or three-letter country code, an aggregate, or a friendly metric alias, and the response echoes back World Bank's own identifiers rather than yours. Aggregate rows in particular come back under codes you never sent. Values below are live August 2026 reads.
| What you pass | What comes back | Measured |
|---|---|---|
| country US (ISO2) | country_id US, countryiso3code USA | GDP series for United States |
| country USA (ISO3) | The same row; the two forms are interchangeable | countryiso3code USA either way |
| country WLD (aggregate) | country_id 1W and countryiso3code null | Population, total 8,215,424,893 for 2025 |
| country EUU (aggregate) | country_id EU | European Union population 451,127,411 for 2025 |
| country HIC (income group) | country_id XD, countryiso3code null | High income population 1,423,739,902 for 2025 |
| indicator NY.GDP.MKTP.CD | indicator_code echoed plus indicator_name GDP (current US$). Real codes are case sensitive | United States 2022 value 26,054,614,000,000 |
| indicator gdp (alias) | Resolves to NY.GDP.MKTP.CD and sets metric to gdp. Aliases are case insensitive | 31 aliases in total, listed by the shortcuts action |
| country US;CN;DE | One data[] entry per indicator and country pair; separate with a semicolon, comma or space | series_count reflects the pair count, not the country count |
| date 2015:2022 | series[] with one row per year, date returned as a string | 8 observations for the range |
unit is an empty string on the indicator, indicator_metadata and search_indicators actions — the unit is embedded in indicator_name instead. Only the shortcuts map and country_profile fill it properly, with values such as current US$, annual % and people.
Real request and response JSON
Captured from the indexed primary action, indicator, on .
{
"method": "POST",
"url": "https://api.reefapi.com/worldbank/v1/indicator",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"country": "US",
"indicator": "NY.GDP.MKTP.CD",
"date": "2015:2022"
}
}{
"ok": true,
"meta": {
"api": "worldbank",
"endpoint": "indicator",
"mode": "live",
"latency_ms": 10065.8,
"record_count": 8,
"bytes": 1780,
"cache_hit": false,
"completeness_pct": 100,
"requests": 1,
"attribution": "Data source: World Bank — World Development Indicators and related collections (https://data.worldbank.org), licensed under Creative Commons Attribution 4.0 International (CC BY 4.0, https://creativecommons.org/licenses/by/4.0/). The World Bank does not necessarily endorse, and is not responsible for, any derived product or interpretation.",
"observations": 8,
"series_count": 1
},
"data": {
"data": [
{
"indicator_code": "NY.GDP.MKTP.CD",
"indicator_name": "GDP (current US$)",
"metric": "gdp",
"country": "United States",
"country_id": "US",
"countryiso3code": "USA",
"unit": "",
"last_updated": "[redacted-phone]",
"series": [
{
"date": "[trimmed-depth]",
"value": "[trimmed-depth]"
},
{
"date": "[trimmed-depth]",
"value": "[trimmed-depth]"
},
{
"date": "[trimmed-depth]",
"value": "[trimmed-depth]"
}
],
"observations": 8,
"latest_value": 26054614000000,
"latest_date": "2022"
}
],
"series_count": 1,
"indicators": [
"NY.GDP.MKTP.CD"
],
"countries": [
"US"
],
"source": "World Bank"
}
}What the World Bank API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| indicator | time-series for one+ indicators (code or shortcut) across one+ countries/all; date/mrv/mrnev, rank | Fintech apps call indicator to get time-series for one+ indicators (code or shortcut) across one+ countries/all; date/mrv/mrnev,…. | country, indicator, date, mrv, mrnev, ... |
| country | country metadata for codes/all or filtered by region/income_level/lending_type | Portfolio dashboards call country to get country metadata for codes/all or filtered by region/income_level/lending_type. | country, region, income_level, lending_type, exclude_aggregates, ... |
| search_indicators | local keyword search over the indicator catalog (WDI default; full=all sources) | Analysts call search_indicators to get local keyword search over the indicator catalog (WDI default; full=all sources). | query, source, full, topic, limit |
| indicator_metadata | definition/source/organization/topics for one+ indicator codes/aliases | Data teams call indicator_metadata to get definition/source/organization/topics for one+ indicator codes/aliases. | indicator |
| country_profile | one-call headline snapshot (most-recent ~10 key metrics) for one+ countries | Fintech apps call country_profile to get one-call headline snapshot (most-recent ~10 key metrics) for one+ countries. | country, metrics |
| shortcuts | list the metric->indicator-code map, or metric=<key>&country=<code> to fetch directly | Portfolio dashboards call shortcuts to list the metric->indicator-code map, or metric=<key>&country=<code> to fetch directly. | metric, country, date, mrv, mrnev |
| reference | reference lists: regions | income_levels | lending_types | sources | topics | Analysts call reference to get reference lists. | kind |
| topic_indicators | browse every indicator in a World Bank topic (Health, Economy, Climate, etc.) by topic id or name; optional keyword filter | Data teams call topic_indicators to get browse every indicator in a World Bank topic (Health, Economy, Climate, etc.) by topic id or…. | topic, query, limit, per_page, max_pages |
Call indicator from your stack
curl -X POST https://api.reefapi.com/worldbank/v1/indicator \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"country":"US","indicator":"NY.GDP.MKTP.CD","date":"2015:2022"}'import requests
r = requests.post(
"https://api.reefapi.com/worldbank/v1/indicator",
headers={"x-api-key": REEF_KEY},
json={
"country": "US",
"indicator": "NY.GDP.MKTP.CD",
"date": "2015:2022"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/worldbank/v1/indicator", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"country": "US",
"indicator": "NY.GDP.MKTP.CD",
"date": "2015:2022"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.worldbank.indicator with {"country":"US","indicator":"NY.GDP.MKTP.CD","date":"2015:2022"}.Who uses this API and why
- Research dashboards call indicator to chart GDP, population or inflation for a country over time.
- Data products use country_profile to pull a full snapshot of a country's development indicators.
- Analysts use search_indicators and topic_indicators to find the right series for a study.
Questions developers ask before integrating
Why is value null for the most recent years?
Because the World Bank has not published that year for that country yet, and the gap is preserved rather than hidden. Syria's GDP over 2018:2025 returned real values through 2022 and then value null for 2023, 2024 and 2025. Two parameters fix this: drop_nulls true removes the empty rows, taking that series from 8 observations to 5, and mrnev N asks for the latest N non-empty points instead.
Why is latest_value null when the series clearly has values?
latest_value follows the last row of the range you asked for, not the last row that has a number. The Syria query above returned latest_date 2025 and latest_value null even though 2022 held 23.7 billion. If you want the last real reading, request it with mrnev 1 or filter series yourself. A measured mrnev 3 on Türkiye inflation returned 2023, 2024 and 2025, all populated.
Does completeness_pct 100 mean the data is complete?
No. It reports that every row the World Bank offered was returned, not that every row has a value. The Syria series with three null years still reported completeness_pct 100.0. Count the non-null entries in series[] yourself, or use drop_nulls and compare observations before and after.
Can I query regions and income groups, not just countries?
Yes, aggregate codes go in the country parameter like any other code, but the identifiers change on the way back. WLD returned country_id 1W, EUU returned EU, and the income group HIC returned XD, with countryiso3code null on both aggregates. The reference action lists what is available: 43 regions, each with a three-letter code and a two-character iso2code, and 7 income levels including LMY for low and middle income combined.
Where is the unit for an indicator?
Not in the unit field, most of the time. indicator, indicator_metadata and search_indicators all returned unit as an empty string or null even for NY.GDP.MKTP.CD, and the only statement of units sits inside indicator_name, GDP (current US$). Two places do carry it: the shortcuts map, which returns unit current US$ for gdp and people for population, and country_profile, whose indicator entries include unit alongside value and date.
How current is the data, and how do I cite it?
Each series carries last_updated, which is the vintage of the underlying collection rather than the latest year of data — measured 2026-07-13 on both a GDP and a poverty series. The latest year that actually holds a number varies per indicator and country: France's profile reported 2025 across its headline metrics while Syria's GDP stopped at 2022. Every response also carries meta.attribution naming the World Bank and CC BY 4.0, which the licence requires you to reproduce.
I do not know the indicator code. How do I find it?
Three ways, cheapest first. shortcuts lists 31 friendly aliases mapped to codes, names and units. search_indicators does a keyword search that defaults to World Development Indicators, source 2, and takes full true to search every source — a search for 'gdp growth' returned exactly 2 matches with their topics attached. topic_indicators browses a whole topic by id or by name such as health or climate.
What is the difference between mrv and mrnev?
mrv counts calendar points backwards from the most recent year, nulls included. mrnev counts only the points that carry a value. On a sparse series the two return different years for the same N, which is why a most-recent-value dashboard should use mrnev and a fixed-grid chart should use mrv or an explicit date range. gapfill true is a third option that carries the last observed value forward into gaps, and it is off by default.
What is the World Bank API?
World Bank API is a ReefAPI endpoint group for global economic indicators by country. It returns live JSON through POST requests under /worldbank/v1.
Is the World Bank API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. World Bank calls use the same shared credit balance as every other ReefAPI engine.
Do I need a World Bank login or account?
No login to World Bank is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the World Bank data?
The page example is captured from a live indicator call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the World Bank API use?
World Bank actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call World Bank from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call worldbank actions with the same key, credit pool and JSON envelope used by normal REST requests.