country list ISO 3166-1 alpha-2 or alpha-3 codes, comma-separated. A code outside this snapshot is a 400, not a silent empty result.
example: country=DE,FR,IT
Country Statistics API
REAL DATAPopulation, GDP, life expectancy and five more World Bank indicators for 215 countries, 1960–2025: latest value, one year, a full annual series or a ranking.
Authoritative reference data or standards computation
- Base URL
- /api/country-stats
- Category
- Geo & Reference
- Capabilities
- 5 routes
- Last updated
GET /api/country-stats
One record per country, alphabetical. Filters compose; count limits the already-filtered list. Aggregates are never returned here.
Route reference
Code samples Ready-to-copy requests in 4 languages
Parameters Route-specific request inputs 7
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
country | list | example: DE,FR,IT | ISO 3166-1 alpha-2 or alpha-3 codes, comma-separated. A code outside this snapshot is a 400, not a silent empty result. |
indicators | list | example: population,gdp,lifeExpectancy | Which indicators to include, comma-separated: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. Omit for all eight. |
year | string | default: latest example: 2000 | `latest` gives each indicator's own most recent observation; a four-digit year between 1960 and 2025 gives exactly that year, or null when nothing was published for it. |
region | enum | default: any allowed: africa | americas | asia | europe | oceania | any example: europe | Restrict to one continental region — the same grouping /api/countries uses, minus `antarctic`: no Antarctic entry has a World Bank economy, so no row here could ever carry it. |
incomeGroup | enum | default: any allowed: high | upper-middle | lower-middle | low | any example: high | Restrict to one World Bank income classification: high, upper-middle, lower-middle or low. |
minPopulation | int | allowed: ≥ 0 example: 100000000 | Only countries whose population in the resolved year is at least this. Countries with no population value for that year are excluded. |
maxPopulation | int | allowed: ≥ 0 example: 1000000 | Only countries whose population in the resolved year is at most this. Countries with no population value for that year are excluded. |
indicators list Which indicators to include, comma-separated: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. Omit for all eight.
example: indicators=population,gdp,lifeExpectancy
year string `latest` gives each indicator's own most recent observation; a four-digit year between 1960 and 2025 gives exactly that year, or null when nothing was published for it.
default: latest
example: year=2000
region enum Restrict to one continental region — the same grouping /api/countries uses, minus `antarctic`: no Antarctic entry has a World Bank economy, so no row here could ever carry it.
default: any
allowed: africa | americas | asia | europe | oceania | any
example: region=europe
incomeGroup enum Restrict to one World Bank income classification: high, upper-middle, lower-middle or low.
default: any
allowed: high | upper-middle | lower-middle | low | any
example: incomeGroup=high
minPopulation int Only countries whose population in the resolved year is at least this. Countries with no population value for that year are excluded.
allowed: ≥ 0
example: minPopulation=100000000
maxPopulation int Only countries whose population in the resolved year is at most this. Countries with no population value for that year are excluded.
allowed: ≥ 0
example: maxPopulation=1000000
Universal parameters Shared response and formatting options 6
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
count | int | default: all matches allowed: 1 – 100 example: 3 | Limit the number of returned records (1–100). Defaults to all matches. |
fields | list | example: country,code | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: indicators | Return all fields except these (comma-separated). |
format | enum | default: json allowed: json | ndjson | csv example: csv | Response format: json envelope, ndjson (one record per line) or csv. |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
count int Limit the number of returned records (1–100). Defaults to all matches.
default: all matches
allowed: 1 – 100
example: count=3
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
example: fields=country,code
exclude list Return all fields except these (comma-separated).
example: exclude=indicators
format enum Response format: json envelope, ndjson (one record per line) or csv.
default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean Pretty-print the JSON response.
default: false
example: pretty=true
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
default: false
example: unwrap=true
Response schema Fields returned in each record 7
| Field | Type | Description | Example |
|---|---|---|---|
country | string | English country name, joined from the ISO 3166-1 dataset. | Germany |
code | string | ISO 3166-1 alpha-2 code. | DE |
alpha3 | string | ISO 3166-1 alpha-3 code — the key the World Bank publishes under. | DEU |
region | string | Continental region shared with /api/countries. | europe |
worldBankRegion | string | World Bank operational region, verbatim (this is what its regional aggregates are built from). | Europe & Central Asia |
incomeGroup | string | World Bank income classification, verbatim. | High income |
indicators | object | One entry per requested indicator: `{ value, year }`. `year` is the year the value was actually observed; both are null where the World Bank publishes nothing — never interpolated. | {"population":{"value":83516593,"year":2024},"gdp":{"value":4685590000000,"year":2024}} |
country string English country name, joined from the ISO 3166-1 dataset.
example: Germany
code string ISO 3166-1 alpha-2 code.
example: DE
alpha3 string ISO 3166-1 alpha-3 code — the key the World Bank publishes under.
example: DEU
region string Continental region shared with /api/countries.
example: europe
worldBankRegion string World Bank operational region, verbatim (this is what its regional aggregates are built from).
example: Europe & Central Asia
incomeGroup string World Bank income classification, verbatim.
example: High income
indicators object One entry per requested indicator: `{ value, year }`. `year` is the year the value was actually observed; both are null where the World Bank publishes nothing — never interpolated.
example: {"population":{"value":83516593,"year":2024},"gdp":{"value":4685590000000,"year":2024}}
Documented examples
Build-generated requests and complete responses 4 Germany's latest headline figures /api/country-stats?country=DE
{
"data": [
{
"country": "Germany",
"code": "DE",
"alpha3": "DEU",
"region": "europe",
"worldBankRegion": "Europe & Central Asia",
"incomeGroup": "High income",
"indicators": {
"population": {
"value": 83491249,
"year": 2025
},
"surfaceArea": {
"value": 357680,
"year": 2023
},
"populationDensity": {
"value": 238.352,
"year": 2023
},
"gdp": {
"value": 5050920000000,
"year": 2025
},
"gdpPerCapita": {
"value": 60496.4,
"year": 2025
},
"lifeExpectancy": {
"value": 80.7927,
"year": 2024
},
"urbanPopulationPercent": {
"value": 82.1382,
"year": 2025
},
"internetUsersPercent": {
"value": 93.5,
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} Population and GDP for the G7 /api/country-stats?country=CA,FR,DE,IT,JP,GB,US&indicators=population,gdp
{
"data": [
{
"country": "Canada",
"code": "CA",
"alpha3": "CAN",
"region": "americas",
"worldBankRegion": "North America",
"incomeGroup": "High income",
"indicators": {
"population": {
"value": 41651653,
"year": 2025
},
"gdp": {
"value": 2319900000000,
"year": 2025
}
}
},
{
"country": "France",
"code": "FR",
"alpha3": "FRA",
"region": "europe",
"worldBankRegion": "Europe & Central Asia",
"incomeGroup": "High income",
"indicators": {
"population": {
"value": 68720337,
"year": 2025
},
"gdp": {
"value": 3366320000000,
"year": 2025
}
}
},
{
"country": "Germany",
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} High-income European countries in 2000 /api/country-stats?region=europe&incomeGroup=high&year=2000
{
"data": [
{
"country": "Andorra",
"code": "AD",
"alpha3": "AND",
"region": "europe",
"worldBankRegion": "Europe & Central Asia",
"incomeGroup": "High income",
"indicators": {
"population": {
"value": 65685,
"year": 2000
},
"surfaceArea": {
"value": 470,
"year": 2000
},
"populationDensity": {
"value": 139.755,
"year": 2000
},
"gdp": {
"value": 1432610000,
"year": 2000
},
"gdpPerCapita": {
"value": 21810.2,
"year": 2000
},
"lifeExpectancy": {
"value": 81.863,
"year": 2000
},
"urbanPopulationPercent": {
"value": 92.2559,
"year": 2000
},
"internetUsersPercent": {
"value": 10.5388,
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} Countries with more than 100 million people /api/country-stats?minPopulation=100000000&indicators=population
{
"data": [
{
"country": "Bangladesh",
"code": "BD",
"alpha3": "BGD",
"region": "asia",
"worldBankRegion": "South Asia",
"incomeGroup": "Lower middle income",
"indicators": {
"population": {
"value": 175686899,
"year": 2025
}
}
},
{
"country": "Brazil",
"code": "BR",
"alpha3": "BRA",
"region": "americas",
"worldBankRegion": "Latin America & Caribbean",
"incomeGroup": "Upper middle income",
"indicators": {
"population": {
"value": 212812405,
"year": 2025
}
}
},
{
"country": "China",
"code": "CN",
"alpha3": "CHN",
"region": "asia",
"worldBankRegion": "East Asia & Pacific",
"incomeGroup": "Upper middle income",
"indicators": {
"population": {
"value": 1406585000,
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} GET /api/country-stats/series
One record per indicator and year, in documented indicator order then year ascending. Years the World Bank does not publish are present with a null value so a gap stays visible.
Route reference
Code samples Ready-to-copy requests in 4 languages
Parameters Route-specific request inputs 4
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
economy
required
| string | example: DEU | ISO 3166-1 alpha-2 or alpha-3 country code, or a World Bank aggregate code such as `WLD` (World) or `EMU` (Euro area). Every record says which it is via `isAggregate`. |
indicators | list | example: population,gdp,lifeExpectancy | Which indicators to include, comma-separated: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. Omit for all eight. |
from | int | allowed: 1960 – 2025 example: 2000 | First year, inclusive. Defaults to 9 years before `to`. |
to | int | allowed: 1960 – 2025 example: 2024 | Last year, inclusive. Defaults to 2025. |
economy string required ISO 3166-1 alpha-2 or alpha-3 country code, or a World Bank aggregate code such as `WLD` (World) or `EMU` (Euro area). Every record says which it is via `isAggregate`.
example: economy=DEU
indicators list Which indicators to include, comma-separated: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. Omit for all eight.
example: indicators=population,gdp,lifeExpectancy
from int First year, inclusive. Defaults to 9 years before `to`.
allowed: 1960 – 2025
example: from=2000
to int Last year, inclusive. Defaults to 2025.
allowed: 1960 – 2025
example: to=2024
Universal parameters Shared response and formatting options 6
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
count | int | default: all matches allowed: 1 – 100 example: 3 | Limit the number of returned records (1–100). Defaults to all matches. |
fields | list | example: economy,alpha3 | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: value | Return all fields except these (comma-separated). |
format | enum | default: json allowed: json | ndjson | csv example: csv | Response format: json envelope, ndjson (one record per line) or csv. |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
count int Limit the number of returned records (1–100). Defaults to all matches.
default: all matches
allowed: 1 – 100
example: count=3
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
example: fields=economy,alpha3
exclude list Return all fields except these (comma-separated).
example: exclude=value
format enum Response format: json envelope, ndjson (one record per line) or csv.
default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean Pretty-print the JSON response.
default: false
example: pretty=true
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
default: false
example: unwrap=true
Response schema Fields returned in each record 7
| Field | Type | Description | Example |
|---|---|---|---|
economy | string | English name of the country or World Bank aggregate. | Germany |
alpha3 | string | ISO 3166-1 alpha-3 code for countries; the World Bank's own three-letter code when `isAggregate` is true. | DEU |
code nullable | string | ISO 3166-1 alpha-2 code; null for aggregates, which have none. | DE |
isAggregate | boolean | True for World Bank groupings (World, Euro area, income groups); false for real countries. | false |
indicator | string | Indicator key: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. | population |
year | integer | Calendar year of this observation. | 2024 |
value nullable | float | The published value, or null when the World Bank publishes nothing for that economy and year. Never interpolated. | 83516593 |
economy string English name of the country or World Bank aggregate.
example: Germany
alpha3 string ISO 3166-1 alpha-3 code for countries; the World Bank's own three-letter code when `isAggregate` is true.
example: DEU
code string nullable ISO 3166-1 alpha-2 code; null for aggregates, which have none.
example: DE
isAggregate boolean True for World Bank groupings (World, Euro area, income groups); false for real countries.
example: false
indicator string Indicator key: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent.
example: population
year integer Calendar year of this observation.
example: 2024
value float nullable The published value, or null when the World Bank publishes nothing for that economy and year. Never interpolated.
example: 83516593
Documented examples
Build-generated requests and complete responses 4 Germany's last ten years /api/country-stats/series?economy=DE
{
"data": [
{
"economy": "Germany",
"alpha3": "DEU",
"code": "DE",
"isAggregate": false,
"indicator": "population",
"year": 2016,
"value": 82348669
},
{
"economy": "Germany",
"alpha3": "DEU",
"code": "DE",
"isAggregate": false,
"indicator": "population",
"year": 2017,
"value": 82657002
},
{
"economy": "Germany",
"alpha3": "DEU",
"code": "DE",
"isAggregate": false,
"indicator": "population",
"year": 2018,
"value": 82905782
},
{
"economy": "Germany",
"alpha3": "DEU",
"code": "DE",
"isAggregate": false,
"indicator": "population",
"year": 2019,
"value": 83092962
},
{
"economy": "Germany",
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} World population since 1960 /api/country-stats/series?economy=WLD&indicators=population&from=1960&to=2025
{
"data": [
{
"economy": "World",
"alpha3": "WLD",
"code": null,
"isAggregate": true,
"indicator": "population",
"year": 1960,
"value": 3021512598
},
{
"economy": "World",
"alpha3": "WLD",
"code": null,
"isAggregate": true,
"indicator": "population",
"year": 1961,
"value": 3062768116
},
{
"economy": "World",
"alpha3": "WLD",
"code": null,
"isAggregate": true,
"indicator": "population",
"year": 1962,
"value": 3117372187
},
{
"economy": "World",
"alpha3": "WLD",
"code": null,
"isAggregate": true,
"indicator": "population",
"year": 1963,
"value": 3184063049
},
{
"economy": "World",
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} Japan's life expectancy in the 1990s /api/country-stats/series?economy=JPN&indicators=lifeExpectancy&from=1990&to=1999
{
"data": [
{
"economy": "Japan",
"alpha3": "JPN",
"code": "JP",
"isAggregate": false,
"indicator": "lifeExpectancy",
"year": 1990,
"value": 78.8371
},
{
"economy": "Japan",
"alpha3": "JPN",
"code": "JP",
"isAggregate": false,
"indicator": "lifeExpectancy",
"year": 1991,
"value": 79.0368
},
{
"economy": "Japan",
"alpha3": "JPN",
"code": "JP",
"isAggregate": false,
"indicator": "lifeExpectancy",
"year": 1992,
"value": 79.0802
},
{
"economy": "Japan",
"alpha3": "JPN",
"code": "JP",
"isAggregate": false,
"indicator": "lifeExpectancy",
"year": 1993,
"value": 79.3037
},
{
"economy": "Japan",
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} Brazil's GDP and GDP per capita this century /api/country-stats/series?economy=BRA&indicators=gdp,gdpPerCapita&from=2000&to=2024
{
"data": [
{
"economy": "Brazil",
"alpha3": "BRA",
"code": "BR",
"isAggregate": false,
"indicator": "gdp",
"year": 2000,
"value": 655448000000
},
{
"economy": "Brazil",
"alpha3": "BRA",
"code": "BR",
"isAggregate": false,
"indicator": "gdp",
"year": 2001,
"value": 559984000000
},
{
"economy": "Brazil",
"alpha3": "BRA",
"code": "BR",
"isAggregate": false,
"indicator": "gdp",
"year": 2002,
"value": 509795000000
},
{
"economy": "Brazil",
"alpha3": "BRA",
"code": "BR",
"isAggregate": false,
"indicator": "gdp",
"year": 2003,
"value": 558234000000
},
{
"economy": "Brazil",
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} GET /api/country-stats/ranking
Countries only — World Bank aggregates are never ranked. Countries with no value for the resolved year are left out of the ranking and reported in meta.warnings; equal values share a rank.
Route reference
Code samples Ready-to-copy requests in 4 languages
Parameters Route-specific request inputs 5
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
indicator | enum | default: population allowed: population | surfaceArea | populationDensity | gdp | gdpPerCapita | lifeExpectancy | urbanPopulationPercent | internetUsersPercent example: gdp | Which indicator to rank by. |
year | string | example: 2000 | `latest` or a four-digit year between 1960 and 2025. Omitted or `latest` resolves to the indicator's most recent comparable year — the newest year still covering at least 80% of the countries it covers in its best year — and the resolved year is echoed in meta.params. |
order | enum | default: desc allowed: desc | asc example: asc | Highest value first (desc) or lowest first (asc). |
region | enum | default: any allowed: africa | americas | asia | europe | oceania | any example: europe | Restrict to one continental region — the same grouping /api/countries uses, minus `antarctic`: no Antarctic entry has a World Bank economy, so no row here could ever carry it. |
incomeGroup | enum | default: any allowed: high | upper-middle | lower-middle | low | any example: high | Restrict to one World Bank income classification: high, upper-middle, lower-middle or low. |
indicator enum Which indicator to rank by.
default: population
allowed: population | surfaceArea | populationDensity | gdp | gdpPerCapita | lifeExpectancy | urbanPopulationPercent | internetUsersPercent
example: indicator=gdp
year string `latest` or a four-digit year between 1960 and 2025. Omitted or `latest` resolves to the indicator's most recent comparable year — the newest year still covering at least 80% of the countries it covers in its best year — and the resolved year is echoed in meta.params.
example: year=2000
order enum Highest value first (desc) or lowest first (asc).
default: desc
allowed: desc | asc
example: order=asc
region enum Restrict to one continental region — the same grouping /api/countries uses, minus `antarctic`: no Antarctic entry has a World Bank economy, so no row here could ever carry it.
default: any
allowed: africa | americas | asia | europe | oceania | any
example: region=europe
incomeGroup enum Restrict to one World Bank income classification: high, upper-middle, lower-middle or low.
default: any
allowed: high | upper-middle | lower-middle | low | any
example: incomeGroup=high
Universal parameters Shared response and formatting options 6
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
count | int | default: 10 allowed: 1 – 100 example: 3 | Limit the number of returned records (1–100). Defaults to 10. |
fields | list | example: rank,country | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: value | Return all fields except these (comma-separated). |
format | enum | default: json allowed: json | ndjson | csv example: csv | Response format: json envelope, ndjson (one record per line) or csv. |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
count int Limit the number of returned records (1–100). Defaults to 10.
default: 10
allowed: 1 – 100
example: count=3
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
example: fields=rank,country
exclude list Return all fields except these (comma-separated).
example: exclude=value
format enum Response format: json envelope, ndjson (one record per line) or csv.
default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean Pretty-print the JSON response.
default: false
example: pretty=true
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
default: false
example: unwrap=true
Response schema Fields returned in each record 10
| Field | Type | Description | Example |
|---|---|---|---|
rank | integer | 1-based position among the countries that have a value for this year; equal values share a rank. | 1 |
country | string | English country name. | India |
code | string | ISO 3166-1 alpha-2 code. | IN |
alpha3 | string | ISO 3166-1 alpha-3 code. | IND |
region | string | Continental region shared with /api/countries. | asia |
worldBankRegion | string | World Bank operational region, verbatim. | South Asia |
incomeGroup | string | World Bank income classification, verbatim. | Lower middle income |
indicator | string | The indicator ranked on: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. | population |
year | integer | The single year every row in this ranking is measured in. | 2025 |
value | float | The published value for that year. | 1463865525 |
rank integer 1-based position among the countries that have a value for this year; equal values share a rank.
example: 1
country string English country name.
example: India
code string ISO 3166-1 alpha-2 code.
example: IN
alpha3 string ISO 3166-1 alpha-3 code.
example: IND
region string Continental region shared with /api/countries.
example: asia
worldBankRegion string World Bank operational region, verbatim.
example: South Asia
incomeGroup string World Bank income classification, verbatim.
example: Lower middle income
indicator string The indicator ranked on: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent.
example: population
year integer The single year every row in this ranking is measured in.
example: 2025
value float The published value for that year.
example: 1463865525
Documented examples
Build-generated requests and complete responses 4 The ten most populous countries /api/country-stats/ranking
{
"data": [
{
"rank": 1,
"country": "India",
"code": "IN",
"alpha3": "IND",
"region": "asia",
"worldBankRegion": "South Asia",
"incomeGroup": "Lower middle income",
"indicator": "population",
"year": 2025,
"value": 1463865525
},
{
"rank": 2,
"country": "China",
"code": "CN",
"alpha3": "CHN",
"region": "asia",
"worldBankRegion": "East Asia & Pacific",
"incomeGroup": "Upper middle income",
"indicator": "population",
"year": 2025,
"value": 1406585000
},
{
"rank": 3,
"country": "United States",
"code": "US",
"alpha3": "USA",
"region": "americas",
"worldBankRegion": "North America",
"incomeGroup": "High income",
"indicator": "population",
"year": 2025,
"value": 341784857
},
{
"rank": 4,
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} The twenty largest economies /api/country-stats/ranking?indicator=gdp&count=20
{
"data": [
{
"rank": 1,
"country": "United States",
"code": "US",
"alpha3": "USA",
"region": "americas",
"worldBankRegion": "North America",
"incomeGroup": "High income",
"indicator": "gdp",
"year": 2025,
"value": 30769700000000
},
{
"rank": 2,
"country": "China",
"code": "CN",
"alpha3": "CHN",
"region": "asia",
"worldBankRegion": "East Asia & Pacific",
"incomeGroup": "Upper middle income",
"indicator": "gdp",
"year": 2025,
"value": 19498000000000
},
{
"rank": 3,
"country": "Germany",
"code": "DE",
"alpha3": "DEU",
"region": "europe",
"worldBankRegion": "Europe & Central Asia",
"incomeGroup": "High income",
"indicator": "gdp",
"year": 2025,
"value": 5050920000000
},
{
"rank": 4,
…
]
}
} Highest life expectancy in Africa /api/country-stats/ranking?indicator=lifeExpectancy®ion=africa
{
"data": [
{
"rank": 1,
"country": "Tunisia",
"code": "TN",
"alpha3": "TUN",
"region": "africa",
"worldBankRegion": "Middle East & North Africa",
"incomeGroup": "Lower middle income",
"indicator": "lifeExpectancy",
"year": 2024,
"value": 76.711
},
{
"rank": 2,
"country": "Algeria",
"code": "DZ",
"alpha3": "DZA",
"region": "africa",
"worldBankRegion": "Middle East & North Africa",
"incomeGroup": "Upper middle income",
"indicator": "lifeExpectancy",
"year": 2024,
"value": 76.475
},
{
"rank": 3,
"country": "Seychelles",
"code": "SC",
"alpha3": "SYC",
"region": "africa",
"worldBankRegion": "Sub-Saharan Africa",
"incomeGroup": "High income",
"indicator": "lifeExpectancy",
"year": 2024,
"value": 76.2951
},
{
"rank": 4,
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} Most sparsely populated countries /api/country-stats/ranking?indicator=populationDensity&order=asc&count=15
{
"data": [
{
"rank": 1,
"country": "Greenland",
"code": "GL",
"alpha3": "GRL",
"region": "americas",
"worldBankRegion": "Europe & Central Asia",
"incomeGroup": "High income",
"indicator": "populationDensity",
"year": 2023,
"value": 0.138543
},
{
"rank": 2,
"country": "Mongolia",
"code": "MN",
"alpha3": "MNG",
"region": "asia",
"worldBankRegion": "East Asia & Pacific",
"incomeGroup": "Upper middle income",
"indicator": "populationDensity",
"year": 2023,
"value": 2.23365
},
{
"rank": 3,
"country": "Australia",
"code": "AU",
"alpha3": "AUS",
"region": "oceania",
"worldBankRegion": "East Asia & Pacific",
"incomeGroup": "High income",
"indicator": "populationDensity",
"year": 2023,
"value": 3.46592
},
{
"rank": 4,
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} GET /api/country-stats/aggregates
The rows WDI ships alongside countries but leaves without a region. They are kept here, separate, so they can never be mistaken for a country in a list or a ranking.
Route reference
Code samples Ready-to-copy requests in 4 languages
Parameters Route-specific request inputs 3
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
aggregate | list | example: WLD,EMU | World Bank aggregate codes, comma-separated — for example WLD, EMU, EUU, HIC. Omit for all of them. |
indicators | list | example: population,gdp,lifeExpectancy | Which indicators to include, comma-separated: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. Omit for all eight. |
year | string | default: latest example: 2000 | `latest` gives each indicator's own most recent observation; a four-digit year between 1960 and 2025 gives exactly that year. |
aggregate list World Bank aggregate codes, comma-separated — for example WLD, EMU, EUU, HIC. Omit for all of them.
example: aggregate=WLD,EMU
indicators list Which indicators to include, comma-separated: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. Omit for all eight.
example: indicators=population,gdp,lifeExpectancy
year string `latest` gives each indicator's own most recent observation; a four-digit year between 1960 and 2025 gives exactly that year.
default: latest
example: year=2000
Universal parameters Shared response and formatting options 6
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
count | int | default: all matches allowed: 1 – 100 example: 3 | Limit the number of returned records (1–100). Defaults to all matches. |
fields | list | example: aggregate,code | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: indicators | Return all fields except these (comma-separated). |
format | enum | default: json allowed: json | ndjson | csv example: csv | Response format: json envelope, ndjson (one record per line) or csv. |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
count int Limit the number of returned records (1–100). Defaults to all matches.
default: all matches
allowed: 1 – 100
example: count=3
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
example: fields=aggregate,code
exclude list Return all fields except these (comma-separated).
example: exclude=indicators
format enum Response format: json envelope, ndjson (one record per line) or csv.
default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean Pretty-print the JSON response.
default: false
example: pretty=true
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
default: false
example: unwrap=true
Response schema Fields returned in each record 4
| Field | Type | Description | Example |
|---|---|---|---|
aggregate | string | The World Bank's own label for the grouping. | Euro area |
code | string | The World Bank's three-letter aggregate code. It is not an ISO 3166-1 code. | EMU |
note nullable | string | The World Bank's own note on what the aggregate covers, verbatim; null where it publishes none. | Euro area aggregate. |
indicators | object | One entry per requested indicator: `{ value, year }`, both null where nothing is published. | {"population":{"value":8215424893,"year":2025}} |
aggregate string The World Bank's own label for the grouping.
example: Euro area
code string The World Bank's three-letter aggregate code. It is not an ISO 3166-1 code.
example: EMU
note string nullable The World Bank's own note on what the aggregate covers, verbatim; null where it publishes none.
example: Euro area aggregate.
indicators object One entry per requested indicator: `{ value, year }`, both null where nothing is published.
example: {"population":{"value":8215424893,"year":2025}}
Documented examples
Build-generated requests and complete responses 3 Every World Bank aggregate /api/country-stats/aggregates
{
"data": [
{
"aggregate": "Africa Eastern and Southern",
"code": "AFE",
"note": "26 countries, stretching from the Red Sea in the North to the Cape of Good Hope in the South (https://www.worldbank.org/en/region/afr/eastern-and-southern-africa)",
"indicators": {
"population": {
"value": 788844284,
"year": 2025
},
"surfaceArea": {
"value": 15173700,
"year": 2023
},
"populationDensity": {
"value": 50.5147,
"year": 2023
},
"gdp": {
"value": 1358690000000,
"year": 2025
},
"gdpPerCapita": {
"value": 1722.39,
"year": 2025
},
"lifeExpectancy": {
"value": 65.3499,
"year": 2024
},
"urbanPopulationPercent": {
"value": 38.7021,
"year": 2025
},
"internetUsersPercent": {
"value": 30.4,
"year": 2025
}
}
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} World and Euro area population and GDP /api/country-stats/aggregates?aggregate=WLD,EMU&indicators=population,gdp
{
"data": [
{
"aggregate": "World",
"code": "WLD",
"note": null,
"indicators": {
"population": {
"value": 8215424893,
"year": 2025
},
"gdp": {
"value": 118350000000000,
"year": 2025
}
}
},
{
"aggregate": "Euro area",
"code": "EMU",
"note": "Euro area aggregate.",
"indicators": {
"population": {
"value": 358664361,
"year": 2025
},
"gdp": {
"value": 18010000000000,
"year": 2025
}
}
}
],
"meta": {
"endpoint": "country-stats",
"route": "/aggregates",
"count": 2,
"params": {
"aggregate": [
"WLD",
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} The four income groups in 2000 /api/country-stats/aggregates?aggregate=HIC,UMC,LMC,LIC&year=2000
{
"data": [
{
"aggregate": "High income",
"code": "HIC",
"note": "For FY27 (July 1, 2026–June 30, 2027), income groups are defined using 2025 GNI per capita (Atlas method): low income (LIC) ($1,175 or less); lower middle income (LMC) ($1,176–$4,635); upper middle income (UMC) ($4,636–$14,375); and high income (HIC) (above $14,375). “Low- and middle-income (LMY)” economies include low-, lower middle-, and upper middle-income groups, while “middle-income (MIC)” economies include lower middle- and upper middle-income groups.",
"indicators": {
"population": {
"value": 1255696330,
"year": 2000
},
"surfaceArea": {
"value": 60165200,
"year": 2000
},
"populationDensity": {
"value": 24.1576,
"year": 2000
},
"gdp": {
"value": 28163000000000,
"year": 2000
},
"gdpPerCapita": {
"value": 22428.2,
"year": 2000
},
"lifeExpectancy": {
"value": 76.0418,
"year": 2000
},
"urbanPopulationPercent": {
"value": 76.1244,
"year": 2000
},
"internetUsersPercent": {
"value": null,
"year": null
}
}
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} GET /api/country-stats/indicators
What each indicator key means, what the World Bank calls it, which organisations produce it and how completely it is populated in this snapshot.
Route reference
Code samples Ready-to-copy requests in 4 languages
Parameters Route-specific request inputs 1
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
indicators | list | example: population,gdp,lifeExpectancy | Which indicators to include, comma-separated: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. Omit for all eight. |
indicators list Which indicators to include, comma-separated: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent, internetUsersPercent. Omit for all eight.
example: indicators=population,gdp,lifeExpectancy
Universal parameters Shared response and formatting options 6
| Parameter | Type | Default & allowed | Description |
|---|---|---|---|
count | int | default: all matches allowed: 1 – 100 example: 3 | Limit the number of returned records (1–100). Defaults to all matches. |
fields | list | example: key,code | Return only these fields (comma-separated). Mutually exclusive with 'exclude'. |
exclude | list | example: observations | Return all fields except these (comma-separated). |
format | enum | default: json allowed: json | ndjson | csv example: csv | Response format: json envelope, ndjson (one record per line) or csv. |
pretty | boolean | default: false example: true | Pretty-print the JSON response. |
unwrap | boolean | default: false example: true | Drop the envelope: return the raw array/object without data/meta wrapper. |
count int Limit the number of returned records (1–100). Defaults to all matches.
default: all matches
allowed: 1 – 100
example: count=3
fields list Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
example: fields=key,code
exclude list Return all fields except these (comma-separated).
example: exclude=observations
format enum Response format: json envelope, ndjson (one record per line) or csv.
default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean Pretty-print the JSON response.
default: false
example: pretty=true
unwrap boolean Drop the envelope: return the raw array/object without data/meta wrapper.
default: false
example: unwrap=true
Response schema Fields returned in each record 12
| Field | Type | Description | Example |
|---|---|---|---|
key | string | The key used by the `indicators` and `indicator` params. | population |
code | string | World Bank series code. | SP.POP.TOTL |
name | string | Indicator name exactly as the World Bank publishes it. | Population, total |
unit | string | Unit the values are expressed in. | people |
definition | string | The World Bank's own definition of the series. | Total population is based on the de facto definition of population… |
sourceOrganization | string | The statistical organisations the World Bank credits upstream of this series, verbatim. | World Population Prospects, United Nations (UN), uri: https://population.un.org/wpp/, publisher: UN Population Division |
firstYear | integer | First year column in the source file. | 1960 |
lastYear | integer | Last year column in the source file. | 2025 |
latestComparableYear | integer | The year /ranking ranks against by default: the newest year still covering at least 80% of the countries this series covers in its best-covered year. | 2025 |
significantDigits nullable | integer | Significant digits kept when packing the snapshot; null when the series is stored exactly as published. | 6 |
countriesWithData | integer | How many of the 215 covered countries have at least one observation. | 215 |
observations | integer | Non-null observations across every economy and year in this series. | 17262 |
key string The key used by the `indicators` and `indicator` params.
example: population
code string World Bank series code.
example: SP.POP.TOTL
name string Indicator name exactly as the World Bank publishes it.
example: Population, total
unit string Unit the values are expressed in.
example: people
definition string The World Bank's own definition of the series.
example: Total population is based on the de facto definition of population…
sourceOrganization string The statistical organisations the World Bank credits upstream of this series, verbatim.
example: World Population Prospects, United Nations (UN), uri: https://population.un.org/wpp/, publisher: UN Population Division
firstYear integer First year column in the source file.
example: 1960
lastYear integer Last year column in the source file.
example: 2025
latestComparableYear integer The year /ranking ranks against by default: the newest year still covering at least 80% of the countries this series covers in its best-covered year.
example: 2025
significantDigits integer nullable Significant digits kept when packing the snapshot; null when the series is stored exactly as published.
example: 6
countriesWithData integer How many of the 215 covered countries have at least one observation.
example: 215
observations integer Non-null observations across every economy and year in this series.
example: 17262
Documented examples
Build-generated requests and complete responses 3 All eight indicators /api/country-stats/indicators
{
"data": [
{
"key": "population",
"code": "SP.POP.TOTL",
"name": "Population, total",
"unit": "people",
"definition": "Total population is based on the de facto definition of population, which counts all residents regardless of legal status or citizenship. The values shown are midyear estimates.",
"sourceOrganization": "World Population Prospects, United Nations (UN), uri: https://population.un.org/wpp/, publisher: UN Population Division;\nStatistical databases and publications from national statistical offices, National Statistical Offices (NSOs), uri: https://unstats.un.org/home/nso_sites/, publisher: National Statistical Offices;\nEurostat: Demographic Statistics, Eurostat (ESTAT), uri: https://ec.europa.eu/eurostat/data/database?node_code=earn_ses_monthly, publisher: Eurostat;\nPopulation and Vital Statistics Report (various years), United Nations (UN), uri: https://unstats.un.org, publisher: UN Statistics Division",
"firstYear": 1960,
"lastYear": 2025,
"latestComparableYear": 2025,
"significantDigits": null,
"countriesWithData": 215,
"observations": 17262
},
{
"key": "surfaceArea",
"code": "AG.SRF.TOTL.K2",
"name": "Surface area (sq. km)",
"unit": "sq. km",
"definition": "Surface area is a country's total area, including areas under inland bodies of water and some coastal waterways.",
"sourceOrganization": "FAO electronic files and web site, Food and Agriculture Organization of the United Nations (FAO), publisher: Food and Agriculture Organization of the United Nations (FAO)",
"firstYear": 1960,
"lastYear": 2025,
"latestComparableYear": 2023,
"significantDigits": 6,
"countriesWithData": 215,
"observations": 16334
},
{
"key": "populationDensity",
"code": "EN.POP.DNST",
"name": "Population density (people per sq. km of land area)",
"unit": "people per sq. km of land area",
"definition": "Population density is midyear population divided by land area in square kilometers. Population is based on the de facto definition of population, which counts all residents regardless of legal status or citizenship--except for refugees not permanently settled in the country of asylum, who are generally considered part of the population of their country of origin. Land area is a country's total area, excluding area under inland water bodies, national claims to continental shelf, and exclusive economic zones. In most cases the definition of inland water bodies includes major rivers and lakes.",
"sourceOrganization": "FAO population estimates, Food and Agriculture Organization of the United Nations (FAO), publisher: Food and Agriculture Organization of the United Nations (FAO);\nWorld Bank population estimates, World Bank (WB), publisher: World Bank (WB)",
"firstYear": 1960,
"lastYear": 2025,
"latestComparableYear": 2023,
…
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} Just population and GDP /api/country-stats/indicators?indicators=population,gdp
{
"data": [
{
"key": "population",
"code": "SP.POP.TOTL",
"name": "Population, total",
"unit": "people",
"definition": "Total population is based on the de facto definition of population, which counts all residents regardless of legal status or citizenship. The values shown are midyear estimates.",
"sourceOrganization": "World Population Prospects, United Nations (UN), uri: https://population.un.org/wpp/, publisher: UN Population Division;\nStatistical databases and publications from national statistical offices, National Statistical Offices (NSOs), uri: https://unstats.un.org/home/nso_sites/, publisher: National Statistical Offices;\nEurostat: Demographic Statistics, Eurostat (ESTAT), uri: https://ec.europa.eu/eurostat/data/database?node_code=earn_ses_monthly, publisher: Eurostat;\nPopulation and Vital Statistics Report (various years), United Nations (UN), uri: https://unstats.un.org, publisher: UN Statistics Division",
"firstYear": 1960,
"lastYear": 2025,
"latestComparableYear": 2025,
"significantDigits": null,
"countriesWithData": 215,
"observations": 17262
},
{
"key": "gdp",
"code": "NY.GDP.MKTP.CD",
"name": "GDP (current US$)",
"unit": "current US$",
"definition": "Gross domestic product is the total income earned through the production of goods and services in an economic territory during an accounting period. It can be measured in three different ways: using either the expenditure approach, the income approach, or the production approach. This indicator is expressed in current prices, meaning no adjustment has been made to account for price changes over time. This indicator is expressed in United States dollars.",
"sourceOrganization": "Country official statistics, National Statistical Organizations and/or Central Banks;\nNational Accounts data files, Organisation for Economic Co-operation and Development (OECD);\nStaff estimates, World Bank (WB)",
"firstYear": 1960,
"lastYear": 2025,
"latestComparableYear": 2025,
"significantDigits": 6,
"countriesWithData": 212,
"observations": 14702
}
],
"meta": {
"endpoint": "country-stats",
"route": "/indicators",
"count": 2,
"params": {
"indicators": [
"population",
"gdp"
]
},
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} Coverage of the internet-usage series /api/country-stats/indicators?indicators=internetUsersPercent&fields=key,countriesWithData,observations,latestComparableYear
{
"data": [
{
"key": "internetUsersPercent",
"countriesWithData": 212,
"observations": 6894,
"latestComparableYear": 2024
}
],
"meta": {
"endpoint": "country-stats",
"route": "/indicators",
"count": 1,
"params": {
"indicators": [
"internetUsersPercent"
]
},
"generatedAt": "2026-09-15T19:47:18.000Z"
}
} About this API
Coverage & behavior
Eight World Bank World Development Indicators series for 215 countries, every year from 1960 to 2025: population, surfaceArea, populationDensity, gdp, gdpPerCapita, lifeExpectancy, urbanPopulationPercent and internetUsersPercent. The snapshot is pinned to the World Bank's 2026-07-13 release, each source CSV recorded by SHA-256 and re-verified by a committed parity script — nothing is fetched while your request is served.
Every value carries the year it was actually observed. year=latest gives each indicator's own most recent publication, which is genuinely different per indicator and per country: population runs to 2025, surface area stops at 2023, and a country with no GDP figure at all (Gibraltar, North Korea, the British Virgin Islands) returns value: null with year: null. Gaps are never interpolated, carried forward or replaced with zero.
Aggregates are not countries and never appear as one. WDI ships "World", "Euro area", "Sub-Saharan Africa", "High income" and 43 other World Bank groupings in the same file as real countries. Here they are split out by joining on ISO 3166-1 alpha-3 codes: the list, ranking and series-by-country routes only ever return real countries, and the 47 aggregates live on their own /aggregates route, each labelled with the World Bank's own note on what it covers.
Coverage is not universal. 34 of the 249 ISO 3166-1 entries have no World Bank economy at all — Antarctica, Taiwan, Western Sahara, the Vatican and most small dependencies — so they cannot be served here; Kosovo and the Channel Islands are excluded because they are outside the /api/countries code space this endpoint joins on. Within the countries that are covered, the newest year is usually a partial release: 185 of 212 countries had a 2025 GDP figure at this snapshot, and only ten had a 2025 internet-usage figure. That is why /ranking ranks against a comparable year — the newest year still covering at least 80% of the countries the series covers in its best year — instead of quietly mixing values from different years into one league table.
Precision. population is stored exactly as published, in whole people. Every other series is rounded to six significant digits, because WDI publishes ratios and national-accounts conversions to fifteen digits that the underlying estimates cannot support (GDP to ten decimal places). The rounding is the only change made to the numbers; it is recorded in every bundled file header and on /notices, as CC BY 4.0 requires.
This endpoint owns the revising statistics. Stable reference facts — codes, capitals, currencies, calling codes, flags — belong to /api/countries, and city-level population to /api/cities.
One concept genuinely appears on both pages, and the two answers differ. surfaceArea here is the World Bank's FAO-sourced series ("a country's total area, including areas under inland bodies of water and some coastal waterways", published per year); areaSqKm on /api/countries is GeoNames' single published constant. They disagree by more than 5% for 28 of the 215 shared countries and wildly for a few: Bermuda 4,290 km² here against 53 there, Greenland 410,450 against 2,166,086 (the World Bank figure excludes the ice sheet), Canada 15,634,400 against 9,984,670. Neither is wrong — they measure different things. Use this one when you want a dated, revisable statistic in a series, and that one when you want a stable geographic constant to sort or filter by.
Use it for
- Fill a country dashboard with real population, GDP and life-expectancy figures instead of invented ones
- Build a 'most populous countries' or 'largest economies' league table from one request
- Chart a country's GDP or urbanisation from 1960 to today as a proper annual series
- Test how your UI handles genuinely missing statistics — nulls here are real gaps, not placeholders
Frequently asked questions
How do I get the population of a country?
/api/country-stats?country=DE&indicators=population returns Germany's most recent published population together with the year it was observed. Add year=2000 for a specific year, or use /api/country-stats/series for the whole annual run.
What are the most populous countries in the world?
/api/country-stats/ranking answers exactly that — it ranks countries by population for the most recent comparable year and defaults to the top ten. ?indicator=gdp ranks by economy size instead, and order=asc flips it.
Does the API include the World total or the Euro area?
Yes, but never inside a country list. The 47 World Bank aggregates — World, Euro area, the income groups, the IDA/IBRD lending groups — are on /api/country-stats/aggregates, and /series accepts an aggregate code such as WLD with isAggregate: true on every record.
Why is a value null instead of a number?
Because the World Bank publishes nothing for that country and year. Missing data is returned as null with a null year — it is never interpolated, carried forward from an earlier year or replaced by zero.
Which countries are missing from this API?
34 ISO 3166-1 entries have no World Development Indicators economy — Antarctica, Taiwan, Western Sahara, the Vatican and most small dependencies. Kosovo and the Channel Islands are also excluded because they are not officially assigned ISO 3166-1 entries.
How current is the data?
It is pinned to the World Bank's 2026-07-13 World Development Indicators release, covering 1960–2025. Each source CSV is recorded by SHA-256 and a committed refresh script re-checks the snapshot against upstream.
Standards & references
Related APIs
ISO 3166 Countries API REAL DATA
All 249 ISO 3166-1 countries and territories: codes, capitals, currencies, languages, area in km², continent, ccTLD, calling codes, flags and map points.
World Cities API REAL DATA
31,000+ world cities from a pinned GeoNames snapshot: coordinates, IANA timezone, elevation, population and capital flag — filter, search or rank by distance.
ISO 4217 Currency Codes API REAL DATA
Every active ISO 4217 currency — code, name, symbol, minor-unit decimals and the countries using it. Search the list or look up one code, with honest 404s.
Mock Time-Series Data API MOCK DATA
Generate compact mock metric series and standalone points with exact intervals, bounded values, coherent trends and deterministic timestamps.
SVG Sparkline & Chart Placeholder API MOCK DATA
Sparkline SVGs straight from a URL — plot 2–100 numbers as a line, area or bar chart with custom size, color and smoothing. No chart library needed.
Country Land Borders & Neighbours API REAL DATA
Land neighbours for all 250 countries and territories, published border lengths in km, the 45 landlocked entries and shortest land-border paths.