253 lines
7.3 KiB
Markdown
253 lines
7.3 KiB
Markdown
---
|
|
title: "World Bank Open Data API"
|
|
task: ""
|
|
lineage_type: import
|
|
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/database-lookup/references/worldbank.md
|
|
upstream_sha: 9c9bd2e9
|
|
imported_at: 2026-06-26
|
|
prompt_class: prompt
|
|
upstream_changes: accepted
|
|
author: upstream
|
|
validated: false
|
|
---
|
|
|
|
# World Bank Open Data API
|
|
|
|
## Base URL
|
|
|
|
```
|
|
https://api.worldbank.org/v2
|
|
```
|
|
|
|
## Authentication
|
|
|
|
**No API key required.** The API is fully open.
|
|
|
|
## Key Endpoints
|
|
|
|
### 1. Get Indicator Data for a Country
|
|
```
|
|
GET /country/{country_code}/indicator/{indicator_code}
|
|
```
|
|
| Parameter | Required | Description |
|
|
|-----------|----------|----------------------------------------------------|
|
|
| format | No | `json`, `xml` (default), `jsonP` |
|
|
| date | No | Year range: `2010:2023`, single year: `2020` |
|
|
| page | No | Page number (default 1) |
|
|
| per_page | No | Results per page (default 50, max 32500) |
|
|
| MRV | No | Most recent values: number of recent data points |
|
|
| gapfill | No | `Y` to fill gaps with most recent value |
|
|
| frequency | No | `M` (monthly), `Q` (quarterly), `Y` (yearly) |
|
|
| source | No | Source ID number |
|
|
|
|
Example (GDP for USA, 2015-2023):
|
|
```
|
|
https://api.worldbank.org/v2/country/US/indicator/NY.GDP.MKTP.CD?format=json&date=2015:2023
|
|
```
|
|
|
|
Example (most recent 5 values):
|
|
```
|
|
https://api.worldbank.org/v2/country/US/indicator/NY.GDP.MKTP.CD?format=json&MRV=5
|
|
```
|
|
|
|
### 2. Get Indicator Data for Multiple Countries
|
|
```
|
|
GET /country/{code1};{code2};{code3}/indicator/{indicator_code}
|
|
```
|
|
Example:
|
|
```
|
|
https://api.worldbank.org/v2/country/US;GB;CN;IN/indicator/SP.POP.TOTL?format=json&date=2020:2023
|
|
```
|
|
|
|
### 3. Get Indicator Data for All Countries
|
|
```
|
|
GET /country/all/indicator/{indicator_code}
|
|
```
|
|
Example:
|
|
```
|
|
https://api.worldbank.org/v2/country/all/indicator/SI.POV.DDAY?format=json&date=2020&per_page=300
|
|
```
|
|
|
|
### 4. Get Indicator Data by Region/Income Group
|
|
```
|
|
GET /country/{aggregate_code}/indicator/{indicator_code}
|
|
```
|
|
Aggregate codes: `EAS` (East Asia), `ECS` (Europe & Central Asia), `LIC` (Low Income), `HIC` (High Income), `WLD` (World), etc.
|
|
|
|
Example:
|
|
```
|
|
https://api.worldbank.org/v2/country/WLD/indicator/NY.GDP.MKTP.CD?format=json&date=2020:2023
|
|
```
|
|
|
|
### 5. List All Countries
|
|
```
|
|
GET /country
|
|
```
|
|
Example:
|
|
```
|
|
https://api.worldbank.org/v2/country?format=json&per_page=300
|
|
```
|
|
|
|
### 6. Get Country Info
|
|
```
|
|
GET /country/{country_code}
|
|
```
|
|
Example:
|
|
```
|
|
https://api.worldbank.org/v2/country/US?format=json
|
|
```
|
|
|
|
### 7. List All Indicators
|
|
```
|
|
GET /indicator
|
|
```
|
|
Example:
|
|
```
|
|
https://api.worldbank.org/v2/indicator?format=json&per_page=100
|
|
```
|
|
|
|
### 8. Search Indicators
|
|
```
|
|
GET /indicator
|
|
```
|
|
Use the query string directly in the URL path or filter by topic/source.
|
|
|
|
By topic:
|
|
```
|
|
https://api.worldbank.org/v2/topic/3/indicator?format=json
|
|
```
|
|
|
|
By source:
|
|
```
|
|
https://api.worldbank.org/v2/source/2/indicator?format=json&per_page=50
|
|
```
|
|
|
|
### 9. List Topics
|
|
```
|
|
GET /topic
|
|
```
|
|
Example:
|
|
```
|
|
https://api.worldbank.org/v2/topic?format=json
|
|
```
|
|
|
|
### 10. List Sources
|
|
```
|
|
GET /source
|
|
```
|
|
Example:
|
|
```
|
|
https://api.worldbank.org/v2/source?format=json
|
|
```
|
|
|
|
## Common Indicator Codes
|
|
|
|
| Indicator Code | Description |
|
|
|------------------------|-------------------------------------------------|
|
|
| NY.GDP.MKTP.CD | GDP (current US$) |
|
|
| NY.GDP.MKTP.KD.ZG | GDP growth (annual %) |
|
|
| NY.GDP.PCAP.CD | GDP per capita (current US$) |
|
|
| NY.GDP.PCAP.PP.CD | GDP per capita, PPP (current intl $) |
|
|
| SP.POP.TOTL | Population, total |
|
|
| SP.POP.GROW | Population growth (annual %) |
|
|
| SP.DYN.LE00.IN | Life expectancy at birth (years) |
|
|
| SP.DYN.TFRT.IN | Fertility rate (births per woman) |
|
|
| SL.UEM.TOTL.ZS | Unemployment (% of total labor force) |
|
|
| FP.CPI.TOTL.ZG | Inflation, consumer prices (annual %) |
|
|
| SI.POV.DDAY | Poverty headcount at $2.15/day (% of pop) |
|
|
| SI.POV.GINI | Gini index |
|
|
| BX.KLT.DINV.CD.WD | Foreign direct investment, net inflows (BoP, US$)|
|
|
| NE.EXP.GNFS.ZS | Exports of goods and services (% of GDP) |
|
|
| EN.ATM.CO2E.PC | CO2 emissions (metric tons per capita) |
|
|
| SE.ADT.LITR.ZS | Literacy rate, adult (% ages 15+) |
|
|
| SH.XPD.CHEX.PC.CD | Current health expenditure per capita (US$) |
|
|
| IT.NET.USER.ZS | Individuals using the Internet (% of pop) |
|
|
|
|
## Common Country Codes (ISO 3166-1 alpha-2)
|
|
|
|
`US` (USA), `GB` (UK), `CN` (China), `IN` (India), `JP` (Japan), `DE` (Germany), `FR` (France), `BR` (Brazil), `ZA` (South Africa), `NG` (Nigeria), `AU` (Australia), `CA` (Canada)
|
|
|
|
## Response Format
|
|
|
|
**Important:** JSON responses are returned as a **two-element array**. The first element is pagination metadata; the second is the data array.
|
|
|
|
### Indicator observations
|
|
```json
|
|
[
|
|
{
|
|
"page": 1,
|
|
"pages": 1,
|
|
"per_page": 50,
|
|
"total": 9,
|
|
"sourceid": "2",
|
|
"lastupdated": "2024-03-28"
|
|
},
|
|
[
|
|
{
|
|
"indicator": {
|
|
"id": "NY.GDP.MKTP.CD",
|
|
"value": "GDP (current US$)"
|
|
},
|
|
"country": {
|
|
"id": "US",
|
|
"value": "United States"
|
|
},
|
|
"countryiso3code": "USA",
|
|
"date": "2023",
|
|
"value": 27360935000000,
|
|
"unit": "",
|
|
"obs_status": "",
|
|
"decimal": 0
|
|
},
|
|
{
|
|
"indicator": { "id": "NY.GDP.MKTP.CD", "value": "GDP (current US$)" },
|
|
"country": { "id": "US", "value": "United States" },
|
|
"countryiso3code": "USA",
|
|
"date": "2022",
|
|
"value": 25462700000000,
|
|
"unit": "",
|
|
"obs_status": "",
|
|
"decimal": 0
|
|
}
|
|
]
|
|
]
|
|
```
|
|
|
|
Note: `value` is `null` when data is unavailable for that year.
|
|
|
|
### Country info
|
|
```json
|
|
[
|
|
{ "page": 1, "pages": 1, "per_page": 50, "total": 1 },
|
|
[
|
|
{
|
|
"id": "US",
|
|
"iso2Code": "US",
|
|
"name": "United States",
|
|
"region": { "id": "NAC", "iso2code": "XU", "value": "North America" },
|
|
"adminregion": { "id": "", "iso2code": "", "value": "" },
|
|
"incomeLevel": { "id": "HIC", "iso2code": "XD", "value": "High income" },
|
|
"lendingType": { "id": "LNX", "iso2code": "XX", "value": "Not classified" },
|
|
"capitalCity": "Washington D.C.",
|
|
"longitude": "-77.032",
|
|
"latitude": "38.8895"
|
|
}
|
|
]
|
|
]
|
|
```
|
|
|
|
## Rate Limits
|
|
|
|
- No formal rate limits published; the API is open and generous.
|
|
- For bulk downloads, use `per_page=32500` to minimize requests.
|
|
- Be respectful: 1-2 requests/second for automated scripts.
|
|
- For very large datasets, consider the World Bank bulk download facility.
|
|
|
|
## Notes
|
|
|
|
- Always include `format=json` -- the default is XML.
|
|
- Results are returned in **descending** date order by default.
|
|
- `null` values are common for recent years (data not yet published) or for indicators with sparse coverage.
|
|
- Pagination: check `pages` in the metadata; iterate `page=1`, `page=2`, etc.
|
|
- Country codes follow ISO 3166-1 alpha-2 (2-letter) in the URL path. The response also includes `countryiso3code`.
|