Population history API
Retrieve annual total population for one country from the World Bank.
economics_ is available through REST and the economics_ MCP tool. Both return the same data shape and use the same credit.
Endpoint and request
GET /v1/economics/{country}/population/observationscurl --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_ with the corresponding arguments below.
Parameters
The accepted period format for this operation is YYYY.
| Name | Required | Type | Meaning |
|---|---|---|---|
country | Yes | path · ISO alpha-3 | One supported uppercase country code; see this operation’s coverage list. |
start | No | query · YYYY | Inclusive first observation period. |
end | No | query · YYYY | Inclusive last observation period. |
limit | No | query · integer, 1–1000 | Maximum number of periods returned. Defaults to 100. A page may contain fewer periods; follow next_cursor. |
cursor | No | query · opaque string | The next_cursor from the previous page. |
version | No | query · first_reported | Accepts `first_reported` only: returns the first stored value per period with `first_reported_at`. Cannot be combined with `as_of`. |
as_ | No | query · YYYY-MM-DD | Returns the series as published through the end of the specified UTC day. Cannot be combined with `version`. |
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
}| Field | Type | Required | Meaning |
|---|---|---|---|
country | string | Yes | The requested uppercase ISO alpha-3 country code. Returned once per page, not for each observation. |
as_ | RFC 3339 timestamp | No | When the source last updated the newest observation on this page, in whole seconds, UTC. |
source | object | Yes | Names the original publishers in publisher and the World Bank, World Development Indicators (CC BY 4.0), in distributor. |
unit | string | Yes | Always person. |
frequency | string | Yes | Always annual. |
observations | array | Yes | Oldest-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[].period | string | Yes | The official month, quarter or year represented by the observation. |
observations[].first_ | RFC 3339 timestamp | No | Present only with version=first_, 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[].value | decimal string | Yes | Mid-year population in whole persons. It counts all residents regardless of legal status or citizenship. The newest years can be projections. |
next_ | string or null | Yes | Pass this unchanged as cursor to read the next page; null on the last page. |
Errors and credits
400 invalid_— The country, period or filter format is invalid, orquery as_andof versionare sent together.400 invalid_— the cursor is malformed, or was issued for other filters or another operation.cursor 401 invalid_— the Bearer key is missing or rejected.api_ key 404 series_— no approved observation matches the request.not_ found 409 cursor_The pagination cursor is too old or the data behind it changed. Restart without the cursor.expired 429 rate_— the network or account short-window limit was reached; retry afterlimit_ exceeded Retry-After.402 insufficient_— your balance does not cover the call.credits 503 economics_— Narwhal cannot safely serve an accepted publication.unavailable
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_ is the update time of the newest observation. Any key can read an earlier vintage with as_ or version=first_. 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.
Start with a free key
Free $10 credits every month, no card.Free $10 credits a month, no card.
Was this page helpful?