# worldbank — World Bank Indicators API


id / implementation	`worldbank` (`apps/worker/src/connectors/datasets/worldbank.ts`)
kind / mode / priority	dataset / api / 2
source	https://api.worldbank.org/v2 (World Development Indicators)
entities	`NormalizedCountryStat` (one per ISO-2 country, key = iso2)
schedule	`dataset: monthly` (WDI is refreshed a few times a year; `lastupdated` was 2026-07-13 on 2026-09-11)
requests per run	6 (country list, 4 indicator series with `mrnev=1`, 1 population time series)
license	CC BY 4.0
attribution	"Source: World Bank, World Development Indicators (CC BY 4.0)"

# License (verified 2026-09-11)

From https://datacatalog.worldbank.org/public-licenses (World Bank Data Catalog → Public licenses):

"Creative Commons Attribution 4.0 (CC-BY 4.0) — The Creative Commons Attribution 4.0 International license allows users to copy, modify and distribute data in any format for any purpose, including commercial use. Users are only obligated to give appropriate credit (attribution) and indicate if they have made any changes, including translations. CC-BY 4.0, with the additional terms below, is the default license for all Datasets produced by the World Bank itself and distributed as open data."

The "additional terms" concern dispute settlement (UNCITRAL arbitration) and the World Bank's privileges and immunities; they do not restrict use. api.worldbank.org/robots.txt returns 404 (no robots restrictions).

# What is fetched

field	indicator	note
`population`	`SP.POP.TOTL`	most recent non-empty value (`mrnev=1`), 2025 for all 264 rows on 2026-09-11
`gdpUsd`	`NY.GDP.MKTP.CD`	GDP, current US$ (2025 for 233 economies, older for 28)
`renewableShare`	`EG.ELC.RNEW.ZS`	percent of total electricity output (0–100), latest year is 2021 for almost every country
`electricityTwh`	derived	`EG.USE.ELEC.KH.PC` (kWh per capita, 2023/2024) × `SP.POP.TOTL` of the same year / 1e9. Flagged in provenance (`method: …+derived-estimate:electricityTwh`, note explains the formula). Only 193 economies have the per-capita figure.
`year`	max of the indicator years	the per-indicator years are listed in `provenance.note`

Aggregates are dropped using the country list (/v2/country?per_page=400: region.value == "Aggregates", 78 entries such as 1W World, ZH Africa Eastern and Southern, EU…), plus anything whose iso2Code is not two letters. 295 entries → 217 countries/economies (includes territories such as HK, PR, XK Kosovo).

NormalizedCountryStat has no per-field facts channel, so per-indicator provenance (URL, year) is carried in the entity provenance note; the entity provenance URL is the country-list document. If per-field provenance becomes needed, add facts?: Fact[] to NormalizedCountryStat in core and the connector will emit them (the data is already available in extract).

# Verified live (2026-09-11)

text

node node_modules/tsx/dist/cli.mjs scripts/try-connector.ts config/connectors/worldbank.yaml --limit 3 --json /tmp/worldbank.json
→ 1 document, 6 fetches, 217 records → 217 entities, 217 valid, 0 rejected, 0 warnings, 8.8 s

Samples: AL population 2 349 580, GDP 30.5 G$, renewableShare 98.6 %, electricityTwh 6.974 (derived, 2023 kWh/capita × 2023 population); DZ population 47 435 312, electricityTwh 84.386, renewableShare 0.91 %; AF has no per-capita electricity figure → electricityTwh: null.

# Quirks

per_page=20000 fits every series in one page; the connector logs a warning if pages > 1.
The population time series uses date=<now-15>:<now> (params.populationYears) so the derived TWh figure never mixes years.
World Bank lists some economies that are not sovereign states (Hong Kong, Macao, Puerto Rico, West Bank and Gaza PS, Kosovo XK). They are kept as-is; countries.iso2 must accept them.
Taiwan is absent from WDI.