Docs

curl

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 "https://codexpopuli.org/v1/data?indicator=population.total&entity=WORLD&dims[variant]=low&year=2050" \
  -H "Authorization: Bearer $API_KEY"

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 (paper, preprint, data-release, policy), or since=YYYY-MM-DD; paginate with the returned nextCursor. See also the human-readable /research page and its /research/rss.xml feed.

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, three views selected by view:

• view=cells (default) — aggregates mean bias, MAPE, and n per revision and horizon bucket. Requires indicator.
• view=milestones — the world population.total walk: each revision’s 2050 and 2100 figure, one entry per revision, in publication order.
• view=raw — cursor-paginated per-entity rows (projected, actual, error, relError), paginated like /v1/research with cursor / limit (default 100, cap 1000).

Shared query params: indicator (single indicator id; required for view=cells, an optional filter otherwise), revision (a projection vintage’s source id, e.g. un-wpp-2010; omit for all revisions), entity (single ISO3 id; omit for all entities), and release (a release id, or latest, the default).

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 1-5, 6-10, and 11-15; horizons beyond 15 years are not scored. 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 below 2.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.

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"

MCP (Model Context Protocol)

Add this to your MCP client config (e.g. Claude Desktop, Claude Code) to query data through an LLM.

{
  "mcpServers": {
    "global-demographics-data": {
      "url": "https://codexpopuli.org/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}