Docs
The API is free to use up to a generous rate limit; sign up for a key for higher limits. All endpoints are described in the interactive API reference.
Quickstart
curl
curl "https://codexpopuli.org/v1/data?indicator=fertility.tfr&entity=JPN"
A key is optional: it raises the limit from 30 to 600 requests per minute. Send it as a bearer token:
curl "https://codexpopuli.org/v1/data?indicator=fertility.tfr&entity=JPN" \ -H "Authorization: Bearer $API_KEY"
Python (requests)
import requests
resp = requests.get(
"https://codexpopuli.org/v1/data",
params={"indicator": "fertility.tfr", "entity": "JPN"},
headers={"Authorization": f"Bearer {API_KEY}"},
)
resp.raise_for_status()
print(resp.json())JavaScript (fetch)
const res = await fetch(
"https://codexpopuli.org/v1/data?indicator=fertility.tfr&entity=JPN",
{ headers: { Authorization: `Bearer ${API_KEY}` } },
);
const data = await res.json();Projection variants (dims[variant])
Indicators driven by UN WPP projections (population.total, fertility.tfr, fertility.births, mortality.life_expectancy) carry low/high projection scenarios alongside the medium (default) series. Pass dims[variant]=low or dims[variant]=high to select one; omit it for the medium series.
curl -g "https://codexpopuli.org/v1/data?indicator=population.total&entity=WORLD&dims[variant]=low&year=2050" \ -H "Authorization: Bearer $API_KEY"
Find a place by name (/v1/entities?q=...)
q finds an entity id from a place name, ignoring case and accents and knowing common aliases: Turkey, Turkiye and Türkiye all find TUR. The best match comes first, at most 10 are returned, and a name that fits two places (Korea, Congo) returns both. It combines with kind and status. /v1/entities?q= includes historical entities such as the USSR; the MCP tool find_place does the same search but leaves them out unless asked.
curl "https://codexpopuli.org/v1/entities?q=turkey"
Derived facts and rankings (/v1/data?view=...)
With view, /v1/data answers one row per entity and source for one indicator, in place of the series (or, for view=rank, one row per entity):
view=first_year_below&threshold=<n>— the first year the value is strictly below the threshold (a value equal to it is not below), andstaysBelow, whether it stays below after that year. The threshold is required, with at most 3 decimal places.view=peak_year— the year of the series’ maximum, the earliest year holding it, compared exactly. It is apeakonly if the last point is lower; otherwiseno_peak_within_series. A query-time view of the pinned data, not a peak record: the series’ own end bounds it, not a projection horizon.view=latest_change— the change between the last two estimates (projections are never used), with both years, the gap and a per-year rate.view=rank&year=<YYYY>— the entities ranked by their value in that one year, highest first (order=ascfor lowest first), the topn(default 10, at most 50). Tied values share a rank, and the next rank skips (1, 2, 2, 4).meta.rankedsays how many of the ranked kinds had a value that year. Countries only unlesskindorentitysays otherwise; one source, sosource=allis refused.
Each reads the headline series (dims[sex]=all for life expectancy) unless dims[...] names another, never a variant. Estimates and projections both count, and nothing is interpolated; a five-year series is keyed to its period’s middle year (UN archive revisions) or first year (WIC). kind keeps only some entity kinds. JSON only. A source=all call for every entity counts as 5 requests against the rate limit; one that names entities counts as one request per 40 of them, at most 3.
curl "https://codexpopuli.org/v1/data?view=first_year_below&indicator=fertility.tfr&threshold=2.1&entity=WORLD&source=all"
curl "https://codexpopuli.org/v1/data?view=peak_year&indicator=population.total&entity=WORLD&source=all"
curl "https://codexpopuli.org/v1/data?view=latest_change&indicator=population.total&kind=country"
curl "https://codexpopuli.org/v1/data?view=rank&indicator=fertility.tfr&year=2023&n=5"
Research feed (/v1/research)
Published items from the daily research aggregator — papers, preprints, data releases, and policy notes gated and tagged by an AI pipeline against the same entity/indicator ids as /v1/data. No API key required. Filter by entity, indicator, type (one or more of paper, preprint, data-release, policy, news, comma-separated; news is only returned when asked for), or since=YYYY-MM-DD; paginate with the returned nextCursor. See also the human-readable /research page and its /research/rss.xml feed. Add ?entity=<id> (a country, a region or WORLD) or ?indicator=<id> to that feed or to /news/rss.xml for one place or one indicator; a place's feed also carries the items tagged WORLD.
curl "https://codexpopuli.org/v1/research?entity=JPN&type=paper&limit=10"
Projection accuracy (/v1/accuracy)
Scores historical UN World Population Prospects revisions against what the platform’s current data now reports for the same entity and year. One route, five views selected by view:
view=cells(default) — aggregates mean bias, MAE, MAPE, andnper revision and horizon bucket. Requiresindicator.view=milestones— each revision’s projected 2050 and 2100 figure, and the last year it projects with that year’s value (finalYear,finalValue), for one entity and indicator (the worldpopulation.totalby default), one entry per revision, in publication order. A revision that ends before 2050 hasnullfor 2050: there is no nearest-year fallback.view=raw— cursor-paginated per-entity rows (projected, actual, error, relError, dims), paginated like/v1/researchwithcursor/limit(default 100, cap 1000).view=horizon— one row per revision and every horizon year, not bucketed:mape,mae,meanBias, the median and the 10th and 90th percentiles of the signed relError (medianRelError,p10RelError,p90RelError, as fractions),nandnOver. Not paginated:cursorandlimitare ignored.view=revision_moves&year=YYYY— for every country, how one UN revision’s value for that one year moved in another (from, default the newest archive revision pinned in the release;to, default the currentun-wpp), projected years included and each side flagged, ranked by the size of the relative move.kind=allorentitywidens it beyond countries;limitdefaults to 50.
Shared query params: indicator (single indicator id: required for view=cells, an optional filter for view=raw; for view=milestones it is population.total (the default) or fertility.tfr; for view=horizon it is population.total (the default) or any other scored indicator, listed below), revision (a projection vintage’s source id, e.g. un-wpp-2010; omit for all revisions; view=milestones ignores it), entity (single ISO3 id; omit for all entities; for view=milestones it defaults to WORLD), and release (a release id, or latest, the default), and, for view=cells and view=horizon, dims[sex] (see below).
Scored indicators: population.total, fertility.tfr, mortality.life_expectancy, mortality.imr (infant mortality), mortality.u5mr (under-5 mortality) and migration.net_rate (net migration rate). Each revision’s projection of them is compared with the current value for the same year, as for population and fertility. The 2010, 2012, 2015, 2017 and 2019 revisions publish these as five-year period figures (2015–2020); the 2022 revision publishes single years. A period figure is scored at the year the UN labels as its period’s MidPeriod (2018 for 2015–2020). For the revisions that publish five-year periods, a net migration rate projection is a five-year average scored against a single year’s actual, so a year with a conflict or a refugee flow shows up as error: part of the net migration error is year-to-year change, not error in the projection. An indicator that no release has scored yet returns no rows.
Population, fertility and life expectancy are scored as a relative error (relError is error / actual), so MAPE is their headline measure; a pair whose actual is 0 is dropped from them, since its relative error is undefined. Infant mortality, under-5 mortality and net migration rate are scored in their own units (deaths per 1,000 live births; people per 1,000 population): an actual of 0 has no relative error, and as an actual approaches 0 the same miss moves the percentage without limit. For them relError is null, so mape and the percentiles are null (never 0), a pair whose actual is 0 is kept, and mae, the average of |error| in those units, is the headline measure. Every cell and every horizon row carries mae. WORLD is left out of net migration rate: the world has no net migration, and the current estimates give it 0. error is projected minus actual: for life expectancy, positive means the projection had people living longer than they did; for infant and under-5 mortality, more deaths; for net migration rate, more net inflow (or less outflow).
Life expectancy is scored as three separate series, dims[sex]=all (the default), dims[sex]=male and dims[sex]=female, each against the actual with the same dims: a male projection is compared with the male value. They are never pooled. Pass dims[sex] to view=cells or view=horizon to choose one; meta.dims says which series the response is. A dims value the indicator has no series for is a 400 that lists the ones it has; the other scored indicators take none. view=raw has no dims filter: it returns every series (of the sources the API serves), and each row says which in dims. In scores.csv.gz the same key is the dims column (sex=male, empty when the indicator has one series).
Every response carries meta.actualsNote: “Actuals are the scoring release’s current best estimates and are themselves revisable.” The comparison is always against the pinned release’s current data, not a fixed ground truth — a later release can revise the same actual, and the score with it.
view=cells rows are bucketed by horizon (years past the projection vintage’s estimate-end year) into five-year buckets: 1-5, 6-10, 11-15, 16-20, 21-25, and 26-30. Cells stop at 30 years. view=raw, and the scores.csv.gz in releases that carry one, hold every scored row of the sources the API serves; display-only sources are left out. view=horizon returns every horizon present, beyond 30 included. Each cell’s shareOverProjected is populated only for fertility.tfr (null for every other indicator): the share of that cell’s scored rows with error > 0 (over-projected), restricted to entities whose current-vintage TFR observation at exactly the scoring release’s estimate-end year is below2.1 (below-replacement) — entities without an observation at that exact year are excluded from both numerator and denominator, not counted as above-replacement. It’s computed row-level, the same basis as mean bias/MAPE/n, not per unique entity: an entity contributing rows to multiple horizon buckets counts once per row, not once per cohort.
view=horizon follows the error year by year. Its horizon is the same as above, but every horizon present is returned (a revision with a short projection has only a few rows), and the same horizon is a different calendar year in different revisions. n counts the (entity, year) rows pooled in that revision and horizon, regional and world aggregates included, so it is not a count of countries. nOver counts rows with error > 0 (the projection was higher than what materialised); a row with an error of exactly 0 is neither over nor under. It is not the same as shareOverProjected, which covers only fertility.tfr rows for below-replacement entities. The percentiles are interpolated between rows. With entity set, n is 1 and the three percentiles all equal the relError of that one row. For the series scored in their own units the percentiles are null.
Rows for UN location codes (LocIDs) with no entity on this site are left out of every UN revision. Those in the 1998 to 2008 revisions include Sudan (Former), Netherlands Antilles, Serbia and Montenegro (1998 to 2004) and State of Palestine (2000 to 2008). Today's Sudan, South Sudan and Taiwan have no rows in the 1998 to 2008 revisions.
curl "https://codexpopuli.org/v1/accuracy?indicator=fertility.tfr&revision=un-wpp-2012"
curl "https://codexpopuli.org/v1/accuracy?view=milestones"
curl "https://codexpopuli.org/v1/accuracy?view=raw&indicator=fertility.tfr&entity=JPN"
curl "https://codexpopuli.org/v1/accuracy?view=horizon&indicator=population.total"
curl -g "https://codexpopuli.org/v1/accuracy?view=horizon&indicator=mortality.life_expectancy&dims[sex]=male"
curl "https://codexpopuli.org/v1/accuracy?view=revision_moves&year=2050"
MCP (Model Context Protocol)
Add this to your MCP client config (e.g. Claude Desktop, Claude Code) to query data through an LLM.
{
"mcpServers": {
"codex-populi": {
"url": "https://codexpopuli.org/mcp"
}
}
}Tool calls draw from the same rate limit as /v1: 30 per minute per IP without a key, 600 per minute with one and at most 1,200 per minute from one IP across keys. A request carries at most 10 messages, so at most 10 tool calls. To use a key, add a headers entry:
{
"mcpServers": {
"codex-populi": {
"url": "https://codexpopuli.org/mcp",
"headers": {
"Authorization": "Bearer <your key>"
}
}
}
}Tools: query_data, get_derived_view, get_accuracy, search_research, list_indicators, get_indicator, list_sources, get_entity, find_place, list_releases, get_release, get_release_diff.
Rate limits
Without a key: 30 requests per minute per IP, shared with everyone behind the same network address. With a key: 600 per minute per key, and at most 1,200 per minute from one IP across all its keys. MCP tool calls count against the same limits.
Anonymous responses may come from a shared cache, and a cached response does not count against your limit. Successful anonymous GET and HEAD responses carry no X-RateLimit-* or x-request-id headers; a 429 keeps them. A 429 carries Retry-After and X-RateLimit-*. Keyed responses carry X-RateLimit-* and are never shared-cached. When reporting a problem, quote the x-vercel-id response header.
A well-formed API key that is unknown or revoked gets 401 and spends one of 10 attempts per minute for the IP it came from. Past that, requests from that IP that carry a well-formed key may get 429, with Retry-After, until the window resets, even with a valid key. A header that is not shaped like an API key gets 401 and spends nothing.
The site counts link-preview fetches (Slack, X and similar) per day, per fetcher and per kind of page. It stores no address, user agent or URL.
Revoking a key
To revoke a key, send DELETE /v1/keys/me with it as the bearer token:
curl -X DELETE https://codexpopuli.org/v1/keys/me -H "Authorization: Bearer $API_KEY"
The answer is 204. Repeating it is harmless: it answers 204 again, or 401 once the key is refused. The key stops working within a minute: the server that answered refuses it almost at once, through /v1 and MCP alike, and others may accept it for up to a minute after they last checked it. Requests that keep sending a revoked key count as failed authentication: past 10 a minute, requests from that IP may get 429, even with a new key, until the window resets. Then get a new key at /keys.
Citing this data
Data values: cite the source each series names (source, resolved to its citation and licence through /v1/sources), and the release id so the result can be reproduced.
Codex Populi’s own numbers are licensed CC BY 4.0: the accuracy measures it computes (error and rel_error in scores.csv.gz; mean bias, MAE, MAPE, medians, percentiles, counts and shares on /v1/accuracy), the changes and moves it computes (change, relChange and changePerYear from /v1/data?view=latest_change; move and relMove from /v1/accuracy?view=revision_moves), the text and counts of release notes and diffs, and the tags the site derives. The projected and actual values in scores, values quoted in release notes and diffs (from/to), and the points the derived views quote (value, endValue, fromValue and toValue) are the named sources’ data and keep their licences: projected that of its source, actual that of un-wpp, and a quoted point that of the source or revision it comes from. Display-only sources (IHME, WIC) appear only on this site: their scores, and any change, move, year, status or other figure derived from their data, are not covered and are not licensed for reuse.
Credit this line: Codex Populi, release <id>, https://codexpopuli.org/releases/<id>.
Full terms: /licences.
Every series in /v1/data is tagged with its source and vintage. Use the catalog endpoints (/v1/sources) to resolve a source id to its full citation string and license.
Example sources: United Nations, DESA, Population Division, World Population Prospects; World Bank, World Development Indicators; Human Mortality Database (mortality.org).
When citing a specific query result, also note the release id from meta.release so the exact snapshot of data can be reproduced via ?release=<id>.
To hear about new releases, subscribe to /releases/rss.xml: one item per published release, and one per dated note on a past release.