{ "openapi": "3.1.0", "info": { "title": "Population API", "version": "1.0.0", "description": "UN population estimates and projections for 237 countries, 1950 to 2100, with 20 demographic indicators.\n\nWorld demographics from 1950 to 2100, from the UN's own projections. The complete World Population Prospects 2024 (Medium variant, CC BY 3.0 IGO): 237 countries plus world, continental and regional aggregates — 84,360 location-years, each carrying 20+ indicators: total/male/female population, density, sex ratio, median age, growth rate, births and birth rate, total fertility rate, deaths and death rate, life expectancy (total/male/female), infant and under-5 mortality, and net migration. Observed estimates through 2023, UN projections from 2024 onward — every row carries an is_projection flag so you always know which side of the line you're on. Pull a country's full trajectory (world: 2.49B in 1950 → 8.23B in 2025 → peaking near 10.3B in the 2080s), a single-year snapshot (India 2024: 1,450,935,791 people, TFR 1.96, median age 28.4), or cross-country rankings for any indicator in any year — including future ones (2100: India 1.51B, China collapsed to 633M, Pakistan #3). Countries resolve by ISO2, ISO3, name or UN code; counts come back in whole persons. Market sizing, actuarial models, policy research, education, journalism — the authoritative demographic dataset, queryable.", "contact": { "name": "Data and APIs", "url": "https://dataandapis.com/contact" }, "termsOfService": "https://dataandapis.com/terms-of-service", "license": { "name": "Data and APIs Terms of Service", "url": "https://dataandapis.com/terms-of-service" }, "x-logo": { "url": "https://dataandapis.com/images/population.webp" } }, "externalDocs": { "description": "Documentation, live tester and pricing", "url": "https://dataandapis.com/apis/population" }, "servers": [ { "url": "https://api-population.dataandapis.com" } ], "tags": [ { "name": "Data", "description": "Population API belongs to the Data category of the Data and APIs catalog." } ], "paths": { "/v1/sources": { "get": { "operationId": "dataSources", "summary": "Data Sources", "description": "Data Sources endpoint of the Population API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/population/data-sources" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "sources": [ { "slug": "un-wpp", "name": "UN World Population Prospects 2024 (Medium variant)", "publisher": "United Nations, DESA, Population Division", "licence": "CC BY 3.0 IGO", "source_url": "https://population.un.org/wpp/", "file_url": "https://population.un.org/wpp/assets/Excel%20Files/1_Indicator%20(Standard)/CSV_FILES/WPP2024_Demographic_Indicators_Medium.csv.gz", "cadence": "biennial revisions; re-scrape on new WPP release", "record_count": 84360, "retrieved_at": "2026-09-06" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/population/rankings": { "get": { "operationId": "rankings", "summary": "Rankings", "description": "Rankings endpoint of the Population API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/population/rankings" }, "parameters": [ { "name": "indicator", "in": "query", "required": false, "schema": { "type": "string" }, "example": "population" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "20" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" }, "example": "desc" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2100" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "indicator": "population", "year": 2100, "is_projection": true, "order": "desc", "rankings": [ { "rank": 1, "name": "India", "iso3": "IND", "iso2": "IN", "value": 1505251761 }, { "rank": 2, "name": "China", "iso3": "CHN", "iso2": "CN", "value": 633368113 }, { "rank": 3, "name": "Pakistan", "iso3": "PAK", "iso2": "PK", "value": 511000618 }, { "rank": 4, "name": "Nigeria", "iso3": "NGA", "iso2": "NG", "value": 476747781 }, { "rank": 5, "name": "Democratic Republic of the Congo", "iso3": "COD", "iso2": "CD", "value": 430709445 }, { "rank": 6, "name": "United States of America", "iso3": "USA", "iso2": "US", "value": 421278889 }, { "rank": 7, "name": "Ethiopia", "iso3": "ETH", "iso2": "ET", "value": 367289596 }, { "rank": 8, "name": "Indonesia", "iso3": "IDN", "iso2": "ID", "value": 295511061 }, { "rank": 9, "name": "United Republic of Tanzania", "iso3": "TZA", "iso2": "TZ", "value": 262834721 }, { "rank": 10, "name": "Bangladesh", "iso3": "BGD", "iso2": "BD", "value": 208596516 }, { "rank": 11, "name": "Egypt", "iso3": "EGY", "iso2": "EG", "value": 201895184 }, { "rank": 12, "name": "Brazil", "iso3": "BRA", "iso2": "BR", "value": 163364064 }, { "rank": 13, "name": "Angola", "iso3": "AGO", "iso2": "AO", "value": 150045574 }, { "rank": 14, "name": "Sudan", "iso3": "SDN", "iso2": "SD", "value": 136890755 }, { "rank": 15, "name": "Mexico", "iso3": "MEX", "iso2": "MX", "value": 130248836 }, { "rank": 16, "name": "Afghanistan", "iso3": "AFG", "iso2": "AF", "value": 130216739 }, { "rank": 17, "name": "Russian Federation", "iso3": "RUS", "iso2": "RU", "value": 126386515 }, { "rank": 18, "name": "Uganda", "iso3": "UGA", "iso2": "UG", "value": 120835192 }, { "rank": 19, "name": "Philippines", "iso3": "PHL", "iso2": "PH", "value": 114221909 }, { "rank": 20, "name": "Yemen", "iso3": "YEM", "iso2": "YE", "value": 110035634 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/population/locations": { "get": { "operationId": "searchLocations", "summary": "Search Locations", "description": "Search Locations endpoint of the Population API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/population/search-locations" }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "example": "korea" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Country" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "locations": [ { "loc_id": 408, "name": "Dem. People's Republic of Korea", "iso3": "PRK", "iso2": "KP", "type": "Country/Area", "parent_id": 906 }, { "loc_id": 410, "name": "Republic of Korea", "iso3": "KOR", "iso2": "KR", "type": "Country/Area", "parent_id": 906 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/population": { "get": { "operationId": "timeSeries", "summary": "Time Series", "description": "Time Series endpoint of the Population API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/population/time-series" }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "example": "world" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2000" }, { "name": "step", "in": "query", "required": false, "schema": { "type": "string" }, "example": "50" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2100" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "location": { "loc_id": 900, "name": "World", "iso3": null, "iso2": null, "type": "World", "parent_id": 0 }, "from": 2000, "to": 2100, "step": 50, "projection_from": 2024, "units": "counts in persons; rates as published (per 1,000 / %)", "series": [ { "year": 2000, "population": 6171702994, "population_male": 3102257632, "population_female": 3069445361, "density": 47.3278, "sex_ratio": 101.069, "median_age": 25.1309, "growth_rate": 1.353, "natural_change": 83518114, "births": 135758482, "birth_rate": 21.997, "fertility_rate": 2.7537, "deaths": 52240368, "death_rate": 8.464, "life_expectancy": 66.4333, "life_expectancy_male": 64.0068, "life_expectancy_female": 68.9201, "infant_mortality": 53.6762, "under5_mortality": 75.5331, "net_migration": 0, "net_migration_rate": 0, "is_projection": false }, { "year": 2050, "population": 9664378587, "population_male": 4838576775, "population_female": 4825801812, "density": 74.1114, "sex_ratio": 100.2647, "median_age": 36.068, "growth_rate": 0.421, "natural_change": 40678556, "births": 132555180, "birth_rate": 13.716, "fertility_rate": 2.0966, "deaths": 91876624, "death_rate": 9.507, "life_expectancy": 77.023, "life_expectancy_male": 74.6551, "life_expectancy_female": 79.4797, "infant_mortality": 17.2667, "under5_mortality": 23.9359, "net_migration": 0, "net_migration_rate": 0, "is_projection": true }, { "year": 2100, "population": 10180160751, "population_male": 5084974935, "population_female": 5095185817, "density": 78.0667, "sex_ratio": 99.7996, "median_age": 42.1254, "growth_rate": -0.127, "natural_change": -12893868, "births": 110028472, "birth_rate": 10.808, "fertility_rate": 1.838, "deaths": 122922340, "death_rate": 12.075, "life_expectancy": 81.7342, "life_expectancy_male": 79.823, "life_expectancy_female": 83.7321, "infant_mortality": 9.6213, "under5_mortality": 13.0566, "net_migration": 0, "net_migration_rate": 0, "is_projection": true } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/population/{country}/{year}": { "get": { "operationId": "yearSnapshot", "summary": "Year Snapshot", "description": "Year Snapshot endpoint of the Population API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/population/year-snapshot" }, "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string" }, "example": "IN" }, { "name": "year", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2024" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "location": { "loc_id": 356, "name": "India", "iso3": "IND", "iso2": "IN", "type": "Country/Area", "parent_id": 5501 }, "units": "counts in persons; rates as published (per 1,000 / %)", "indicators": { "year": 2024, "population": 1450935791, "population_male": 748323427, "population_female": 702612364, "density": 488.0064, "sex_ratio": 106.5059, "median_age": 28.4413, "growth_rate": 0.896, "natural_change": 13629928, "births": 23186978, "birth_rate": 15.981, "fertility_rate": 1.9622, "deaths": 9557050, "death_rate": 6.587, "life_expectancy": 72.2353, "life_expectancy_male": 70.729, "life_expectancy_female": 73.8556, "infant_mortality": 22.6273, "under5_mortality": 28.1953, "net_migration": -630830, "net_migration_rate": -0.435, "is_projection": true } } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 1 token per call." } } }, "security": [ { "ApiKey": [] } ] }