Media

World Population

Population of every country from the World Bank World Development Indicators API (api.worldbank.org): population and previous-year population, yearly change, growth rate, share of world population, surface and land area, density, urban share, fertility rate, region, income level and capital, ranked by population.

world-populationpopulationcountriesdemographicsworld-bankmedia

3 rows in the dataset

Download the dataset

Get every row this scraper has collected as one CSV or JSONL file. If the data is older than maxAgeHours, the scraper is re-run with its configured settings first. The key needs the datasets:export scope.

DOWNLOAD_ID=$(curl -s -X POST "https://api.pandorlabs.com/v1/datasets/world-population/downloads" \  -H "Authorization: Bearer $PANDORLABS_KEY" \  -H "Content-Type: application/json" \  -d '{"maxAgeHours":24,"format":"csv"}' | jq -r '.id')while true; do  STATUS=$(curl -s "https://api.pandorlabs.com/v1/downloads/$DOWNLOAD_ID" \    -H "Authorization: Bearer $PANDORLABS_KEY" | jq -r '.status')  [ "$STATUS" != "refreshing" ] && break  sleep 5donecurl -s "https://api.pandorlabs.com/v1/downloads/$DOWNLOAD_ID/file" \  -H "Authorization: Bearer $PANDORLABS_KEY" \  -o dataset.csv

At its current 3 rows, this download costs 1 credit when the data is fresh enough, or 2 credits when it has to be refreshed first.

The rate is 1 credit per 100 rows cached and 2 credits live, charged on the rows in the dataset when the download becomes ready. A failed refresh is not charged. The file stays downloadable for 24 hours. See pricing.

Start a run

To choose the targets yourself, send the parameters below as input. The call returns 202 with the run; the key needs the scrapers:run scope and the account a positive credit balance.

curl -X POST "https://api.pandorlabs.com/v1/scrapers/world-population/runs" \  -H "Authorization: Bearer $PANDORLABS_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "includeAggregates": false,      "maxCountries": 300,      "requestDelayMs": 400    }  }'

A run is billed at the live rate once it finishes: 2 credits per 100 rows it collected. A run that collects nothing costs nothing.

Parameters

Every parameter is optional. Anything you leave out uses the default shown here; an unknown name or an invalid value is rejected with a 400 that lists each problem.

Targeting

year
number
Year
Reference year for population. Empty means the latest year the World Bank has published a world total for. Area, density, urbanisation and fertility use the latest value at or before that year.
Default
none
Range
at least 1961
Example
2024
includeAggregates
boolean
Include regional aggregates
Also emit World Bank aggregates such as World, regions and income groups. They are never ranked.
Default
false

Advanced

maxCountries
number
Max rows per run
Default
300
Range
1 to 400
requestDelayMs
number
Delay between requests (ms)
Default
400
Range
300 to 30000

Input as JSON Schema

The same schema the API validates against. Use it as a tool input schema or to generate a typed client.

inputSchema

{  "type": "object",  "additionalProperties": false,  "properties": {    "year": {      "type": "number",      "minimum": 1961,      "title": "Year",      "description": "Reference year for population. Empty means the latest year the World Bank has published a world total for. Area, density, urbanisation and fertility use the latest value at or before that year.",      "examples": [        "2024"      ]    },    "includeAggregates": {      "type": "boolean",      "title": "Include regional aggregates",      "description": "Also emit World Bank aggregates such as World, regions and income groups. They are never ranked.",      "default": false    },    "maxCountries": {      "type": "number",      "minimum": 1,      "maximum": 400,      "title": "Max rows per run",      "default": 300    },    "requestDelayMs": {      "type": "number",      "minimum": 300,      "maximum": 30000,      "title": "Delay between requests (ms)",      "default": 400    }  }}

Run, poll, read rows

The run is asynchronous. Poll it until it reaches a terminal status and its billing is paid, then page through its rows. Until then the rows endpoint answers 409 (still queued or running) or 402 (payment required).

RUN_ID=$(curl -s -X POST "https://api.pandorlabs.com/v1/scrapers/world-population/runs" \  -H "Authorization: Bearer $PANDORLABS_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "includeAggregates": false,      "maxCountries": 300,      "requestDelayMs": 400    }  }' | jq -r '.id')while true; do  RUN=$(curl -s "https://api.pandorlabs.com/v1/runs/$RUN_ID" \    -H "Authorization: Bearer $PANDORLABS_KEY")  STATUS=$(echo "$RUN" | jq -r '.status')  BILLING=$(echo "$RUN" | jq -r '.billing.status')  case "$STATUS" in queued|running) ;; *) [ "$BILLING" != "pending" ] && break ;; esac  sleep 5doneecho "$RUN" | jq '{status, rowCount, billing}'curl -s "https://api.pandorlabs.com/v1/runs/$RUN_ID/rows?page=1&limit=100" \  -H "Authorization: Bearer $PANDORLABS_KEY"

See the API reference for pagination, cancelling and listing runs.

Output fields

Rows have no fixed schema; these are the fields observed in the rows collected so far. Coverage is the share of rows where the field is present.

Field	Type	Coverage
capital_city	string	100%
country	string	100%
country_code	string	100%
density_computed_per_km2	number	100%
density_per_km2	number	100%
fertility_rate	number	100%
flag_url	string	100%
growth_rate_pct	number	100%
income_level	string	100%
indicator_years	object	100%
is_aggregate	boolean	100%
iso2_code	string	100%
land_area_km2	number	100%
latitude	number	100%
longitude	number	100%
population	number	100%
previous_year_population	number	100%
rank	number	100%
region	string	100%
surface_area_km2	number	100%
urban_population_pct	number	100%
world_percentage	number	100%
year	number	100%
yearly_change	number	100%
yearly_change_pct	number	100%
created_at	date	100%
updated_at	date	100%
_id	string	100%