The world in numbers
The optional statistics pack (about 150 KB) adds eleven basic indicators for every country from 1960, from the World Bank’s World Development Indicators: population, population density, urban population, life expectancy, births and deaths, forest and agricultural land, access to electricity and drinking water, and internet use.
In 30 seconds
>>> from pyworldatlas import Atlas
>>> with Atlas() as atlas:
... print(atlas.time_series("Kenya", "electricity_access").summary)
Access to electricity in Kenya rose from 10.9% of people in 1993 to 77.0% of people in 2024.
pyworldatlas get statistics
A country over time
time_series() returns the yearly values, a sentence
about the change, and a one-line chart you can print anywhere:
>>> from pyworldatlas import Atlas
>>> atlas = Atlas()
>>> japan = atlas.time_series("Japan", "life_expectancy")
>>> japan.summary.startswith("Life expectancy at birth in Japan rose from 67.7 years in 1960")
True
>>> len(japan.sparkline(width=20)) <= 20
True
Use "world" for the World Bank’s world total:
>>> atlas.time_series("world", "population").latest.value > 8_000_000_000
True
One value
statistic() returns the latest published value, or
the value for a year. Each value knows its unit and year:
>>> str(atlas.statistic("Brazil", "urban_population", 1960))
'44.7% of people (1960)'
Ranking
rank() ranks countries by any indicator, the same
way it ranks area or coastline. Without a year each country uses its latest
published value, and every row says which year that is. Ranking only orders
the published numbers; it does not say which is better.
>>> top = atlas.rank("forest_area", limit=3)
>>> all(row.value > 90 for row in top)
True
>>> top[0].unit, top[0].source.startswith("World Bank")
('% of land', True)
>>> [indicator.key for indicator in atlas.indicators()][:3]
['birth_rate', 'death_rate', 'drinking_water']
>>> atlas.close()
From the command line:
$ pyworldatlas stat Kenya electricity_access
Access to electricity in Kenya rose from 10.9% of people in 1993 to 77.0% of people in 2024.
1993 ▁▁▂▂▂▃▃▃▃▄▄▅▆▇██ 2024
$ pyworldatlas stat Japan life_expectancy
Life expectancy at birth in Japan rose from 67.7 years in 1960 to 84.0 years in 2024.
1960 ▁▂▃▃▃▄▄▅▅▅▆▆▆▇▇▇▇▇████ 2024
On a world map
world_map() colors every country by one
indicator, using each country’s latest value or the value for one year. It
needs a map pack as well (pyworldatlas get maps-lite). Countries fall into
five classes that each hold about the same number of countries, from light
(smaller numbers) to dark (larger numbers). Countries without a value are
hatched and marked “No data”.
>>> atlas = Atlas()
>>> world = atlas.world_map("life_expectancy")
>>> world.title
'Life expectancy at birth (years), latest year'
>>> world.to_svg().startswith("<svg")
True
>>> atlas.close()
show() opens the map in your browser, write_html() saves a page with
the map and a table of every value, and write_svg() saves just the image.
In a notebook the map displays on its own. Hover over a country to see its
value and year. The map is drawn with plain SVG on the Equal Earth
projection, which keeps every country’s area in proportion; nothing is
downloaded when it opens.
$ pyworldatlas world-map forest_area
$ pyworldatlas world-map population --year 2000 --output population-2000.html
How the numbers are kept
Values are kept exactly as the World Bank publishes them, with the year they describe. Each indicator names its original source, such as the United Nations Population Division.
A year with no published value stays empty; nothing is estimated or filled in. Small territories the World Bank does not cover have no values.
Countries are matched by their ISO 3166 code. The World Bank’s world total is included; its regional and income groupings are not.
Numbers describe places, not people’s worth. See the official statistics section of the editorial policy in the repository.
Source: World Bank, World Development Indicators, licensed under CC BY 4.0. PyWorldAtlas is not affiliated with or endorsed by the World Bank. See Data sources and freshness.