Overview
A collector pulls five World Bank indicators daily: total population (SP.POP.TOTL), annual growth (SP.POP.GROW), urban population share (SP.URB.TOTL.IN.ZS), population density (EN.POP.DNST) and life expectancy at birth (SP.DYN.LE00.IN). It stores one record per country per year from 1960 and keeps the newest year as the latest record.
`country` accepts ISO 3166 alpha-2 or alpha-3 codes; two-letter codes are mapped to three-letter ones before lookup, and Kosovo is handled as XK. Without `year` you get the newest stored year. `year` (paid) must be between 1960 and the current year, otherwise the request is rejected with a 400, and a year with no record returns a 404.
The response always wraps the figures in a `historical` array with one entry, and `count` is 1. `population` is the raw count and `populationFormatted` its readable form. `growthRate` is the year-on-year change in percent and can be negative. `density` is people per square kilometre of land and `urbanPercent` is the urban share in percent, both rounded to two decimals. Indicators publish on different schedules, so the newest year often has a population count before density or life expectancy are released; those fields are null until the World Bank fills them, and a reported zero is kept as zero rather than treated as missing.
`worldRank` ranks the country by `population` among the countries and territories that report a population that year (about 217); World Bank regional, income and lending aggregates are excluded. Ranking is per year, so a historical lookup returns the rank for that year. Ties share a rank and the next rank is skipped. `rankedCountries` is the number ranked, and `worldPercent` is the population divided by the World Bank world total (`WLD`) for the year, as a percentage to four decimals; the world total also counts Taiwan, which the World Bank does not list separately, so the shares of all ranked countries add up to slightly under 100. All three are null when the year has no ranking or the code is not a ranked country.
Live Test Population Data API →
Endpoint
One host, one path per API. The block below shows this call in four languages; every one of them is the same HTTP request. Making requests covers the timeouts, retries and parameter rules that apply to all of them. The SDKs wrap the same call in a typed client.
curl "https://api.apiverve.com/v1/population?country=US&year=2023" \
-H "x-api-key: your_api_key_here"const res = await fetch('https://api.apiverve.com/v1/population?country=US&year=2023', {
headers: { 'x-api-key': 'your_api_key_here' },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data } = await res.json();
console.log(data);import requests
res = requests.get(
"https://api.apiverve.com/v1/population?country=US&year=2023",
headers={"x-api-key": "your_api_key_here"},
timeout=15,
)
res.raise_for_status()
print(res.json()["data"])package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.apiverve.com/v1/population?country=US&year=2023", nil)
req.Header.Set("x-api-key", "your_api_key_here")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}Replace your_api_key_here with the key from your dashboard. When the inputs arrive as a list rather than one at a time, batch requests run up to 200 of them through this same API in a single call.
Authentication
Send your key in the x-api-key header. That is the only auth step — there is no token exchange and no per-endpoint scope to configure. Authentication covers creating, rotating and revoking keys.
A 401 means the key is missing, invalid or expired. A 403 means the key is valid but not permitted here — blocked by a key restriction or an IP allow-list. Running out of credits is a 429.
Parameters
Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them.
| Parameter | Type | Description |
|---|---|---|
countryRequired | string | ISO 2 or 3-letter country code (e.g., US, USA, GB, GBR) length 2–3 |
yearOptionalPremium | integer | Specific year to retrieve data for (1960-present). Returns latest if not specified. range 1960–2030 |
Response
Every API returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape. Response format covers the envelope, the other output formats and how premium fields are withheld.
{
"status": "ok",
"error": null,
"data": {
"country": "US",
"countryName": "United States",
"year": 2025,
"count": 1,
"historical": [
{
"year": 2025,
"population": 341784857,
"populationFormatted": "341.78 million",
"growthRate": 0.52,
"urbanPercent": 80.19
}
]
}
}
Response fields
Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.
| Field | Type | Example | Description |
|---|---|---|---|
country | string | "US" | ISO 2-letter country code for the country |
countryName | string | "United States" | Full name of the country in English |
year | number | 2025 | Year of the population data retrieved |
count | number | 1 | Number of historical records returned |
historical | array[1] | Population figures for the requested year (one entry) | |
year | number | 2025 | Year the figures in this entry describe |
populationPremium | number | 341784857 | Total population count for the country |
populationFormattedPremium | string | "341.78 million" | Population count in human-readable format |
growthRatePremium | number | 0.52 | Annual population growth rate as percentage |
urbanPercentPremium | number | 80.19 | Percentage of population living in urban areas |
Errors
Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change. Error handling covers the full status list and which of them are worth retrying.
| Status | Meaning | What to do |
|---|---|---|
400 | Input was rejected | Read error; it names the parameter. |
401 | Key missing or invalid | Check the header name and the key value. |
403 | Key valid, but not permitted | A key restriction or IP allow-list; see key scoping. |
429 | Rate limited, or out of credits | Read error to tell them apart; see rate limits. |
Use cases
- Market Expansion Sizing
- When evaluating entry into emerging markets, retail planners pull total population and urban percentage to gauge addressable customer density.
- Demographic Trend Modeling
- Academic research tools query historical growth rates and life expectancy across decades to model regional aging patterns.
- Broadband Network Planning
- Telecom planners cross-reference population density and urban shares to prioritize where to deploy new broadband fiber networks.
- Sovereign ESG Scoring
- To assess national health and development indicators, sovereign ESG platforms fetch country life expectancy and population growth figures.
Other ways to use Population Data
Set up Population Data on APIVerve, or reach the same source a different way. Your APIVerve account and credits work on all of them — one key, one balance.
Related
More in Finance: