# WorldPop API > Official API of WorldPop (University of Southampton) for population estimates: how many people live in a country, an administrative region, any polygon or one 100 m grid cell, with their age and sex, for every year 2015-2030. Data: WorldPop Global2, release R2025A, 100 m grid, CC BY 4.0. Base URL: https://api.worldpop.org/v3 ## Pick the right call - A named country or region: GET /search, then GET /countries/{iso3} or GET /units/{unit_id}. - All regions of a country: GET /countries/{iso3}/units. - A city, a district or any other shape: POST /population with its polygon (GeoJSON); age and sex: POST /agesex; indicators: POST /indicators; age groups: POST /groups. Without a polygon: POST /catchment around the city's centre. - Change over time: POST /trend, or several years on any data call (`"years": [2015, 2030]` in a POST body; `years=2015,2030` or `years=all` on GET). - Around points (clinics, schools): POST /catchment. - People around health facilities (hospitals, clinics, health posts, ...): POST /profiles/exposure with `facilities` (of a type in an area, or named ones); never type facility coordinates. - Age and sex groups (children under 5, women of reproductive age 15-49, school age 5-14, 65 and over, or any ages and sex) in a profile: `groups` on /profiles/place, /profiles/compare and /profiles/exposure. - People an event affects near points, lines or polygons (a flood zone, a blast or plume, a road or river corridor, a coastline), weighted by distance: POST /exposure. - Many shapes at once: POST /batch. - One spot: GET /point. - A complete overview in one answer (a report with sections, tables, chart specifications and Markdown): GET or POST /profiles/place (a country, a region or an area), /profiles/compare (2-8 places), GET /profiles/country-map (a country's regions coloured by a metric), POST /profiles/exposure (people an event affects), GET /profiles/world-map (every country coloured by a metric), GET /profiles/ranking (the top or bottom N countries, or regions of a country). - A map by country, or "which countries (or regions) have the highest / lowest ...": GET /profiles/world-map and GET /profiles/ranking answer from WorldPop's own country and region numbers; use them rather than another source. - A map file (GeoTIFF of people per cell) of a region or a country: GET /raster?unit_id= or ?iso3= (a link); of any polygon: POST /raster. A whole large country: GET /countries/{iso3}/files (WorldPop's own files). Regions (units) are first-level administrative regions (states, provinces, counties), not cities; a search result for one has `"level": "admin1"`. Unit and country numbers are the 100 m data aggregated to WorldPop's administrative units. Counting the returned boundary (`geometry=true`) through the polygon endpoints gives the same people up to cells along the edge, because the boundary is simplified. Coordinates are [longitude, latitude] (EPSG:4326). Every data call takes `year` (2015-2030) or `years` (a list; on GET calls also `all`), except POST /trend, which takes `from_year` and `to_year` (default 2015 and 2030). ## Endpoints - GET /search?q=&limit= : countries and regions by name (accents, case, hyphens and apostrophes do not matter; other names such as "Cote d'Ivoire" or "Czechia" work) or ISO3 code. Example: https://api.worldpop.org/v3/search?q=Guera -> `{"results": [{"type": "unit", "unit_id": 4990, "name": "GuĂ©ra", "iso3": "TCD", "country": "Chad", "level": "admin1"}]}` - GET /countries?year= : every country with region, area, number of regions and population. Example: https://api.worldpop.org/v3/countries?year=2026 -> 246 countries; Kenya `total_population` 58082677.62. - GET /countries/{iso3}?year=&include=&geometry= : one country. `include`: population (default), agesex (age pyramid), indicators (median age, sex ratio, dependency ratios), groups (under 5, women 15-49, 65+, ...). `geometry=true` adds the boundary as GeoJSON (a country's can be about 1 MB: ask for it only when it is needed). Example: https://api.worldpop.org/v3/countries/KEN?year=2026 -> `total_population` 58082677.62, `units` 8, `area_km2` 585702.58. - GET /countries/{iso3}/units?year=&include= : every region of a country with population, density, `share_of_total` and `rank`. Example: https://api.worldpop.org/v3/countries/KEN/units?year=2026 -> 8 regions; Nairobi (unit_id 7) 6310587.8 people, rank 5. - GET /units/{unit_id}?year=&include=&geometry= : one region. Example: https://api.worldpop.org/v3/units/7?year=2026 -> Nairobi, Kenya: `total_population` 6310587.8, `population_density` 8276.65 per km2. - GET /point?lon=&lat=&year=&include= : people in the 100 m grid cell under a point, and its country and region; `include=agesex` adds the cell's age pyramid. `population` is 0 for a cell where nobody lives in a country with data, and null only where no country's data covers the point (sea, outside the data). Example: https://api.worldpop.org/v3/point?lon=36.8219&lat=-1.2864&year=2026 -> `population` 81.88 people in the cell, `unit` "Nairobi", `country` "Kenya", `cell_area_km2` 0.008546. - POST /population {"geojson", "year" | "years"} : people inside a polygon. Example body: `{"geojson": {"type": "Polygon", "coordinates": [[[32.55, 0.28], [32.65, 0.28], [32.65, 0.37], [32.55, 0.37], [32.55, 0.28]]]}, "year": 2025}` (central Kampala) -> `total_population` 1258765.36, `area_km2` 110.78. - POST /agesex {"geojson", "year" | "years", "age_range"?, "sex"?} : the age pyramid (20 age classes x 2 sexes) and the people of the chosen ages and sex. `age_range` widens to whole age classes (0, 1-4, 5-9, ..., 90+); the answer's `age_range` is what was counted. Same Kampala box, `"age_range": [0, 4]` -> 157799.45 children under 5. - POST /indicators {"geojson", "year" | "years"} : median age, sex ratio, dependency ratios, ageing index (`aging_index`), child-woman ratio, age shares. Kampala box 2025 -> `median_age` 22.5, `sex_ratio` 95.6. - POST /groups {"geojson", "year" | "years", "groups"?} : people in preset or custom age and sex groups. Kampala box 2025 -> under_5 157799.45, women_15_49 420461.97. - POST /trend {"geojson", "from_year"?, "to_year"?} : population every year, change and peak. Kampala box 2015-2030 -> +55.45 %, 2.98 % a year, peak 2030. - POST /batch {"features": FeatureCollection, "year" | "years", "include"?} : each feature's population, share and rank (up to 1000 features). A feature's `id` is its GeoJSON `id`, else `properties.id`, else its position (0, 1, ...); its `name` is `properties.name`, else `properties.shapeName`, `properties.NAME` or the deepest `properties.ADM_NAME` (none: no `name`). - POST /catchment {"points": [{"id"?, "lon", "lat"}], "radii_km": [...], "year" | "years"} : people within each distance of each point. Example: a point in Kampala (32.58, 0.31), radii 1, 5, 10 km, 2025 -> 35556.29, 950524.89 and 2942970.26 people within them. - POST /exposure {"geometry" | "features", "radius_km", "p"?, "decay"?, "polygons"?, "rings_km"?, "include"?, "year" | "years"} : people an event at points, along lines or around polygons affects. Everyone within `radius_km` (R, at most 100) of the nearest feature counts with the weight w = (1 - exp(-(1 - d/R)^p)) / (1 - exp(-1)) of their distance d: 1 at the feature, 0 at R. `exposed_population` is the weighted sum (an estimate weighted by distance, not a count of people harmed), `population_within` everyone within R, `rings` both by distance band (`rings_km`, default four equal bands). Choose R as the farthest distance the event reaches and p (above 0, at most 10, default 1) as how quickly it fades: 0.5 when it stays strong almost to R (a flood zone: weight 0.80 at R/2), 1 (0.62), 2-4 when it is concentrated near the source (a blast or plume: 0.35, 0.10); `"decay": "none"` counts everyone within R fully. `"polygons": "area"` (default) counts everyone inside a polygon fully (`population_inside`) and fades outward; `"edge"` measures from the boundary on both sides (a coastline). `geometry` is one GeoJSON Point, MultiPoint, LineString, MultiLineString, Polygon or MultiPolygon; `features` a FeatureCollection of them (up to 1000, ids and names as /batch), each person counted once, for the nearest feature; `total` has everyone once. `include`: agesex, indicators or groups of the exposed people. Example: `{"geometry": {"type": "Point", "coordinates": [36.8219, -1.2864]}, "radius_km": 10, "year": 2025}` (central Nairobi) -> `exposed_population` 1438346.14, `population_within` 3286975.33; with `"p": 2` 778229.29; with `"decay": "none"` 3286975.33. - POST /raster {"geojson" | "unit_id" | "iso3", "year", "layer"?, "age_range"?, "sex"?, "bands"?, "resolution"?, "describe"?} : a GeoTIFF of people per cell (float32, EPSG:4326, nodata -99999 outside the area and where the data has no value, 0 where nobody lives) for one year. `layer`: population (default) or agesex (the chosen `age_range` and `sex`; `bands`: sum, one band, or each, one band per age class and sex, f_00 ... m_90). `resolution`: 100m (default) or 1km (each 1 km cell is the sum of the 100 m cells in it, on the grid of WorldPop's 1 km files). The cells add up to what POST /population (or /agesex) gives for the same area: a unit is its boundary as `geometry=true` gives it, a country all of its own 100 m data (equal to GET /countries/{iso3}). Headers: `X-Total-Population` (people in the file), `X-Area-Km2`, `X-Agesex-Coverage` (agesex). `describe=true` answers JSON about the file (name, size in cells, people, the GET link) instead. Example: the Kampala box above, 2025 -> `X-Total-Population` 1258765.36, 121 x 109 cells, about 45 KB. - GET /raster?unit_id=|iso3=&year=&layer=&age_range=15,64&sex=&bands=&resolution=&describe= : the same for a unit or a country, as a link (send the key as the X-API-Key header). Example: https://api.worldpop.org/v3/raster?unit_id=7&year=2025 -> worldpop_population_2025_100m_unit7.tif, 6191760.56 people (Nairobi's boundary counted: POST /population of it gives the same; /units/7 gives 6191842.4 for the unit), about 270 KB; https://api.worldpop.org/v3/raster?iso3=RWA&year=2025 -> 14406699.42 people (= /countries/RWA), about 7.4 MB. Files hold at most 25,000,000 cells (times the bands); larger: 413 `raster_too_large` with WorldPop's own files of the country in `details.files` (Kenya at 100 m: 413; at 1 km: 1.5 MB). - GET /countries/{iso3}/files?year=|years= : where WorldPop publishes a country's own GeoTIFFs: population and age and sex (a zip of the 40 bands, and each band), 100 m and 1 km (null for a country without data); `global.population.1km`, the world's 1 km population file of the year; `citation` (the text and DOI of each set of files: population 100 m WP00839, 1 km WP00840; age and sex 100 m WP00841, 1 km WP00842); `licence` (CC BY 4.0). The same files are described in WorldPop's STAC catalogue (https://api.stac.worldpop.org) for STAC tools: `stac.collection` is the country's collection, `stac.items` the year's items. `years` (a list or `all`) answers `years: [...]`, one entry per year. Example: https://api.worldpop.org/v3/countries/RWA/files?year=2025 -> `population.100m` https://data.worldpop.org/GIS/Population/Global_2015_2030/R2025A/2025/RWA/v1/100m/constrained/rwa_pop_2025_CN_100m_R2025A_v1.tif, `stac.items.population.100m` https://api.stac.worldpop.org/collections/RWA/items/rwa_pop_2025_CN_100m_R2025A_v1 - GET /profiles/place?iso3=|unit_id=|place_name=&year= and POST /profiles/place {"iso3" | "unit_id" | "place_name" | "geojson" (with "name"?), "year"?} : a population profile. `year` defaults to the current year; the trend covers 2015-2030. Sections (`sections[].id`): population (people, area, density), trend (every year, `change` with percent and annual growth, `peak`), age_sex (the pyramid, 20 classes x 2 sexes), indicators (median age, dependency ratios, children under 5, 65 and over, women 15-49), then for a country `units` (every region ranked: population, share, density, growth; most and least populous, highest and lowest growth), for a region `rank` (its rank and share in its country), for an area `context` (the region its centre lies in), and source (licence and citation). Each section has `sentences`, a `table` ({columns, rows, formats}), `data` (its numbers) and `charts` ({id, title, spec}: `spec` is a complete Vega-Lite v5 specification, its data inline); `summary` has a few sentences and `markdown` the whole answer. `place_name` takes the best match of GET /search and names it in `place.matched`. Example: https://api.worldpop.org/v3/profiles/place?iso3=KEN&year=2026 -> 58,082,678 people, 46.6 million in 2015 to 62.5 million in 2030 (+34.3 %), median age 21.2, 8 regions, Rift Valley the most populous. - GET /profiles/compare?places=KEN,UGA,TZA&year= and POST /profiles/compare {"places": [2-8 of the above], "year"?} : places side by side (population, area, density, growth 2015-2030, median age, shares under 5 and 65+), trend lines (people and an index, 2015 = 100), the pyramids as shares of each population. In GET `places`, an ISO3 code, a unit id or a name. - GET /profiles/country-map?iso3=&metric=&year=&classes= : a choropleth of a country's regions. `metric`: population, density, growth (percent 2015-2030), under_5_share, age_65_plus_share or median_age; `classes` 3-7 (quantile breaks, default 5). The map chart's data holds the regions' boundaries, simplified to about 90 KB for the whole country. Example: https://api.worldpop.org/v3/profiles/country-map?iso3=NGA&metric=under_5_share&year=2026 -> 37 regions, 9.9 % (Anambra) to 18.8 % (Katsina). - GET /profiles/world-map?metric=&year=&classes=&from_year=&to_year= : every country coloured by a metric (the metrics of the country map; `from_year`/`to_year` for growth only, default 2015-2030). Each country's value, rank, class and population; the class breaks (quantiles, `classes` 3-7) and legend; the highest, lowest and median country; the countries without data (grey: `no_data`); the small countries also as dots (`small`). The map chart is Vega-Lite with the Equal Earth projection; its outlines are the countries' own boundaries simplified for a whole-world map (60 S to 84 N, about 60 KB of GeoJSON in all, cut at the antimeridian). Example: https://api.worldpop.org/v3/profiles/world-map?metric=age_65_plus_share&year=2026 - GET /profiles/ranking?metric=&year=&n=&order=&level=&iso3=®ion=&from_year=&to_year= : the top (`order=top`, the highest values) or bottom N (`n` 1-50, default 10) countries worldwide, or the regions of one country (`iso3=NGA`) or of several (`iso3=NGA,GHA`; `level=countries` ranks the listed countries themselves), optionally only in one continent (`region`: Africa, Americas, Asia, Europe or Oceania). Each place's rank among all those compared (1 = the highest), value and population; the median and the number of places with data; a horizontal bar chart. Examples: https://api.worldpop.org/v3/profiles/ranking?metric=under_5_share&n=10&year=2026, https://api.worldpop.org/v3/profiles/ranking?iso3=NGA&metric=density&n=37 - `groups` on the profiles (POST: preset names under_1, under_5, age_5_14, age_15_24, age_15_64, age_65_plus, women_15_49 and/or {"name", "age_range": [min, max], "sex"}; GET: `groups=under_5,women_15_49`) adds a "groups" section: each group's people and share; in an exposure report each group's people within R and exposed, in total and by distance band. Without `groups` the answers are as before. - POST /profiles/exposure with {"facilities": {"place_name": "Nairobi", "types": ["hospital"]}, "radius_km": 5, "rings_km": [1, 2], "groups": ["under_5", "women_15_49"]} instead of a geometry counts the people around those facilities (at most 500); with {"facilities": {"place_name": "Nairobi", "names": ["Kenyatta National Hospital", "Mbagathi District Hospital"]}, ...} around the facilities named (case ignored; the whole name, else the one name containing it; a name not found, or found more than once in the area, is a 422 naming only it). A section gives the people nearest to each facility. - POST /profiles/exposure {"geometry" | "features", "radius_km", "p"?, "polygons"?, "rings_km"?, "name"?, "year"?} : a report of POST /exposure: the people within R and exposed, the distance bands, the age and sex of the exposed people (under 5, 65 and over), the estimate for p 0.5, 1, 2 and 4 and without decay (from the same count), the weight explained, and the regions the area within R overlaps. - GET /profiles/place.png, /profiles/compare.png, /profiles/country-map.png, /profiles/world-map.png, /profiles/ranking.png (same parameters as without .png) and POST /profiles/place.png, /profiles/compare.png, /profiles/exposure.png (same bodies): the answer as a ready image (PNG, 1200 px wide, light background, with the source line): the country map and the world map with their legend of classes; the ranking as bars with the median; key figures, the trend and the age-sex pyramid of a place; trend lines and a pyramid per place of a comparison; the area within R shaded by the weight, the weight curves and the distance bands of an exposure report. Show these images as they are rather than redrawing the data. Example: https://api.worldpop.org/v3/profiles/country-map.png?iso3=NGA&metric=under_5_share - Every profile is ONE request against the quota and the limits; an area is counted for every year 2015-2030 at once, so an area too large for POST /trend over 16 years is too large here. - GET /catalog : dataset, release, years, licence, citation and endpoints; `stac`, WorldPop's STAC catalogue, which describes WorldPop's own files of the dataset for STAC tools. - GET /health : service state and every limit. ## Limits From GET /health (`limits`): without a key 1000 requests a day, 60 a minute and 3 counting requests at once per address, and polygons up to 100,000 km2; with a key 10,000 requests a day, 300 a minute, 6 at once and larger areas. Without a key one request may also read half as much (`anon_max_request_size`, `anon_max_raster_cells`). Send requests one after another, not in parallel. Every counted answer has `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (the day, UTC) and `X-RateLimit-Minute-Limit`, `X-RateLimit-Minute-Remaining` and `X-RateLimit-Minute-Reset` (the clock minute, UTC); a 429 has `Retry-After` in seconds. At most 50,000 vertices and 1000 parts per request, 16 years per request, latitudes -60 to 84. POST /exposure: the area within `radius_km` of the features counts against the area limit; `radius_km` up to 100, `p` up to 10, up to 1000 features; a request that would take more than about 10 s (very many people within the radius, or lines folded on themselves) is 413 `cost_limit_exceeded` (a 100 km radius around one point always fits). Place lookups have no area limit. ## Speed and method Every call is answered in its own response: there is no task to poll and no need to wait between calls (keep to the limits above). Measured on 3 November 2026 (median of five calls, time at the server): POST /population for Nairobi 0.02 s, POST /agesex 0.04 s, POST /trend over 16 years 0.16 s, POST /population for Rwanda (25,305 km2) 0.38 s, POST /exposure with a 10 km radius 0.06 s; the network adds its round trip (0.04-0.07 s from Southampton). The API reads only the 100 m cells under the area from copies of WorldPop's GeoTIFFs on its own disk and takes age and sex from each administrative unit's 40 shares; a cell counts when its centre is inside the area. https://api.worldpop.org/v3/documentation/method explains it. ## Keys Anonymous use works. A key raises the limits: register at https://api.worldpop.org/v3/register and say what the key is for and where it will be used (the required "intended use" field, `intended_use` in POST /auth/register: at least 30 characters, at most 1000; keys are approved by WorldPop, who read it to decide; questions to info@worldpop.soton.ac.uk); once WorldPop has authorised the account, the key is emailed to you. Send it as the `X-API-Key` header or as `Authorization: Bearer ` (or, for MCP connectors that cannot send headers, in the MCP URL: see below). ## Errors Errors are JSON: `{"error", "message", "details"}`. - 401 `invalid_api_key`: the key is not a key of any account. 403 `key_not_authorized`: the account is not authorised yet; `account_blocked`: the account was blocked. Without a key the call works at the anonymous limits. - 404 `not_found` means only an unknown code or id (e.g. ISO3 "KENYA", a unit_id from memory): call GET /search to find the right one. - A `total_population` (or `population`) of null: no data for that place and year; report it as missing, never substitute another place's or year's figure. - 413 `area_limit_exceeded`, `cost_limit_exceeded`, `too_many_parts`, `geometry_too_complex`: split the area or ask for fewer years; `request_too_large`: the body is over 10 MB; `raster_too_large`: ask for 1 km, fewer bands or a smaller area, or use the files in `details.files`. - 422 `validation_error` / `invalid_geometry`: fix the request as the message says (coordinates are [longitude, latitude]); `no_data`: there is no data for that area or country. - 429 `concurrency_limit_exceeded`: too many of your requests are running at once; `minute_limit_exceeded`: too many requests this minute. Wait `Retry-After` seconds (also `details.retry_after_seconds`) and retry; these are not counted. 429 `rate_limit_exceeded`: the daily quota is used up; stop until `Retry-After` (midnight UTC). 429 `too_many_attempts`: an account endpoint (sign-in, registration, password reset) refused further attempts for now. - 503 `data_unavailable`, `year_unavailable`, `storage_unavailable`: try again later. 504 `count_timeout`: the count did not finish in time; split the area or ask for fewer years. ## Licence and citation CC BY 4.0. Cite WorldPop for every figure: - Population: WorldPop R2025A v1, DOI 10.5258/SOTON/WP00839 (https://hub.worldpop.org/doi/10.5258/SOTON/WP00839) - Age and sex: WorldPop R2025A v1, DOI 10.5258/SOTON/WP00841 (https://hub.worldpop.org/doi/10.5258/SOTON/WP00841) GET /catalog has the full citation texts. WorldPop's own 1 km files have DOIs of their own (GET /countries/{iso3}/files, `citation`). ## MCP Every endpoint except /health and POST /raster is also a tool of the MCP server at https://api.worldpop.org/v3/mcp (Streamable HTTP; 23 tools such as search_places, get_country, get_unit, list_country_units, population_at_point, population_in_area, age_sex_in_area, estimate_exposure, and the profile tools build_place_profile, compare_places, build_country_map, build_exposure_report, build_world_map and rank_places, whose answer is a summary line, a ready image (PNG) of the map or charts to show as it is and the Markdown report, with the whole answer as structured content). The server also has six prompts (place_profile, compare_places, country_map, exposure_report, world_map, ranking) that tell the assistant which profile tool to call and how to present it: the ready image, a short summary, the sections in order with their tables, and the citation. A GeoTIFF cannot travel through MCP: raster_link gives the GET link of a unit's or a country's file with the people it holds, and country_files WorldPop's own files; a polygon's GeoTIFF needs POST /raster. Add it to an assistant as a remote MCP server (custom connector) with that URL. For a key's limits send `X-API-Key` (or `Authorization: Bearer `); connectors that cannot send headers (claude.ai, ChatGPT) take the key in the URL: https://api.worldpop.org/v3/mcp?key=YOUR_KEY. A tool refuses arguments it does not take. ## More - https://api.worldpop.org/v3/llms-full.txt: this guide plus every parameter and field. - https://api.worldpop.org/v3/openapi.json: the OpenAPI schema. - https://api.worldpop.org/v3/documentation: the documentation pages. - https://api.worldpop.org/v3/documentation/moving-from-v2: for code written for the previous version (https://api.worldpop.org/v2, deprecated and to be retired): what changed. - https://api.worldpop.org/v3/documentation/method: how the API counts, measured times, accuracy, and how the previous version differed. - https://api.worldpop.org/v3/documentation/exposure: what an exposure estimate means, the weight, and how to choose R and p.