---
title: "Population history API Reference | Narwhal API"
description: "Retrieve annual total population for one country from the World Bank. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/population-history"
---

# 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`.

| 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_of` | No | query · YYYY-MM-DD | Returns 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
}
```

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `country` | string | Yes | The requested uppercase ISO alpha-3 country code. Returned once per page, not for each observation. |
| `as_of` | 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_reported_at` | RFC 3339 timestamp | No | Present 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[].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_cursor` | string or null | Yes | Pass 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](https://narwhalapi.com/docs/errors.md).

## 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](https://narwhalapi.com/docs/freshness.md).

## 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](https://narwhalapi.com/api/fx.md).

Return to [all Economics operations](https://narwhalapi.com/docs/api/economics.md).

## Start with a free key

Free $10 credits every month, no card.Free $10 credits a month, no card.

[Get a free API key](https://narwhalapi.com/signup)

Was this page helpful?
