Browse all documentation

Population history API

Retrieve annual total population for one country from the World Bank.

economics_get_population_history is available through REST and the economics_get_population_history MCP tool. Both return the same data shape and use the same credit.

Endpoint and request

REST endpoint
GET /v1/economics/{country}/population/observations
Example request
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/population/observations?start=2024&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP uses tool economics_get_population_history with the corresponding arguments below.

Parameters

The accepted period format for this operation is YYYY.

NameRequiredTypeMeaning
countryYespath · ISO alpha-3One supported uppercase country code; see this operation’s coverage list.
startNoquery · YYYYInclusive first observation period.
endNoquery · YYYYInclusive last observation period.
limitNoquery · integer, 1–1000Maximum number of periods returned. Defaults to 100. A page may contain fewer periods; follow next_cursor.
cursorNoquery · opaque stringThe next_cursor from the previous page.
versionNoquery · first_reportedAccepts `first_reported` only: returns the first stored value per period with `first_reported_at`. Cannot be combined with `as_of`.
as_ofNoquery · YYYY-MM-DDReturns the series as published through the end of the specified UTC day. Cannot be combined with `version`.

Response

Example response
{
  "country": "USA",
  "as_of": "2026-10-08T00:00:00Z",
  "source": {
    "publisher": "UN Population Division (World Population Prospects), national statistical offices, Eurostat, U.S. Census Bureau, Pacific Community: mid-year estimates",
    "distributor": "World Bank, World Development Indicators (CC BY 4.0)"
  },
  "unit": "person",
  "frequency": "annual",
  "observations": [
    {
      "period": "2024",
      "value": "340003797"
    },
    {
      "period": "2025",
      "value": "341784857"
    }
  ],
  "next_cursor": null
}
FieldTypeRequiredMeaning
countrystringYesThe requested uppercase ISO alpha-3 country code. Returned once per page, not for each observation.
as_ofRFC 3339 timestampNoWhen the source last updated the newest observation on this page, in whole seconds, UTC.
sourceobjectYesNames the original publishers in publisher and the World Bank, World Development Indicators (CC BY 4.0), in distributor.
unitstringYesAlways person.
frequencystringYesAlways annual.
observationsarrayYesOldest-first accepted observations, one per period. Missing source values are omitted, never filled. A page can hold fewer observations than limit; follow next_cursor until it is null.
observations[].periodstringYesThe official month, quarter or year represented by the observation.
observations[].first_reported_atRFC 3339 timestampNoPresent only with version=first_reported, this UTC timestamp records when Narwhal first stored the period (the latest time if its measures were stored separately); periods released before capture began show Narwhal's first capture.
observations[].valuedecimal stringYesMid-year population in whole persons. It counts all residents regardless of legal status or citizenship. The newest years can be projections.
next_cursorstring or nullYesPass this unchanged as cursor to read the next page; null on the last page.

Errors and credits

  • 400 invalid_query — The country, period or filter format is invalid, or as_of and version are sent together.
  • 400 invalid_cursor — the cursor is malformed, or was issued for other filters or another operation.
  • 401 invalid_api_key — the Bearer key is missing or rejected.
  • 404 series_not_found — no approved observation matches the request.
  • 409 cursor_expired The pagination cursor is too old or the data behind it changed. Restart without the cursor.
  • 429 rate_limit_exceeded — the network or account short-window limit was reached; retry after Retry-After.
  • 402 insufficient_credits — your balance does not cover the call.
  • 503 economics_unavailable — Narwhal cannot safely serve an accepted publication.

Only a successful data response costs credit. See all errors, headers, and retry rules.

Freshness

By default, this route returns Narwhal's current accepted series; the response as_of is the update time of the newest observation. Any key can read an earlier vintage with as_of or version=first_reported. Vintage history starts at Narwhal's first capture and is not a reconstruction of every past publication.

Official sources can be sparse and expose different historical depths. Narwhal omits missing observations rather than interpolating or carrying values forward.

Read how source checks, validation, stored releases, and failed checks work.

Current public-beta coverage

215 Countries

ABW, AFG, AGO, ALB, AND, ARE, ARG, ARM, ASM, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BFA, BGD, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BWA, CAF, CAN, CHE, CHL, CHN, CIV, CMR, COD, COG, COL, COM, CPV, CRI, CUB, CUW, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESP, EST, ETH, FIN, FJI, FRA, FRO, FSM, GAB, GBR, GEO, GHA, GIB, GIN, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUM, GUY, HKG, HND, HRV, HTI, HUN, IDN, IMN, IND, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MUS, MWI, MYS, NAM, NCL, NER, NGA, NIC, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SLB, SLE, SLV, SMR, SOM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKM, TLS, TON, TTO, TUN, TUR, TUV, TZA, UGA, UKR, URY, USA, UZB, VCT, VEN, VGB, VIR, VNM, VUT, WSM, YEM, ZAF, ZMB, ZWE

Annual history starts in 1960, and in 1990 for Palestine. Kosovo and the Channel Islands have no ISO alpha-3 code and are not covered. There is no latest-value population route. Each successful call is billed as an Economics call.

Indonesia and regional Economics routes are not public. Daily FX is available through the FX API.

Return to all Economics operations.

Was this page helpful?