PyWorldAtlas

Offline · source-aware · made for learning

Geography data that feels like ordinary Python.

Explore country profiles, names and writing systems, capitals, cities, physical geography, climate classes, coordinates, distances, reviewed land neighbors, rankings, and learning tools from one bundled database. Built for classrooms, curious learners, and developers. No API key and no runtime download.

Documented version: 0.8.1 | Dataset: 2026.07.22.7 | Python: 3.10–3.14 | Profiles: 248

248

country and area profiles

6,265

bundled populated places

0

runtime dependencies

A small taste of the atlas

Brazil · Japan · Switzerland · China · France · United Arab Emirates

Flag values are Unicode regional-indicator emoji derived from each alpha-2 code. The row above uses local documentation artwork for consistent display; see Discovery tools for the exact API and rendering contract.

Start with something interesting

>>> from pyworldatlas import Atlas
>>> with Atlas() as atlas:
...     brazil = atlas.country("Brazil")
...     print(brazil.flag, brazil.name_in("pt"), "—", brazil.capital.name)
...     print(brazil.highest_point.name, f"{brazil.highest_point.elevation_m:,.0f} m")
...     print(", ".join(river.name for river in brazil.rivers[:3]))
...     print(brazil.climate.dominant_zone.code, brazil.climate.dominant_zone.name)
🇧🇷 Brasil — Brasília
Pico da Neblina 2,994 m
Amazon, Río de la Plata/Paraná, Tocantins
Aw Tropical, savannah

The installed wheel contains ordinary Python source and one read-only database. Constructing Atlas never contacts a server and does not load every country into memory.

See what you can build

Meet a country

Combine local names, flag emoji, capital, anthem title, motto, demonym, currency, languages, timezones, and source references in one typed profile. Start with Country profiles.

Explore the physical world

Read coastlines, area components, elevation extremes, source-listed rivers and lakes, and represented Köppen-Geiger classes. Visit Physical geography.

Measure between places

Calculate great-circle distance, initial bearing, and spherical midpoint from cities, capitals, countries, or coordinates. Try Coordinates and distances.

Follow land connections

Discover reviewed neighbors, shared neighbors, shortest land-border paths, crossings, and connected components in Land borders and paths.

Discover and compare

Compose exact filters, inspect nearby capitals, and rank sourced or transparently derived values with Rankings and nearby capitals.

Teach and learn

Create stable samples, deterministic flashcards, compact discovery cards, multiple-choice questions, and Unicode-preserving JSON with Learning activities, Discovery tools, and Serialization.

Choose your next step

New to PyWorldAtlas?

Follow the concise Quickstart to install the package, open an atlas, and make your first useful queries.

Want to try it first?

Open the Playground and run the package in your browser with no local setup.

Ready to build?

Copy a complete program from Example programs or browse the focused guides under Explore the atlas.

What is bundled

Dataset 2026.07.22.7
Records	Coverage
Countries and areas	248
Primary capitals	241 / 248
Populated places	6,265
Selected local-language identities	248 / 248
Sourced English formal names	240 / 248
Anthem titles	234 / 248
Reviewed source-listed mottos	32 / 248
English demonym profiles	227 / 248
Country timezone profiles	246 / 248, 417 records
Country-language metadata	722 records across 245 profiles
Reviewed land-border relationships	319
Total-area profiles	248 / 248
Land area and coastline	238 / 248 each
Highest and lowest points	240 / 248 each
Source-listed river records	188 across 80 profiles
Source-listed lake records	187 across 69 profiles
Plain-language climate summaries	240 / 248
Köppen-Geiger climate profiles	241 / 248

Designed for exploration

PyWorldAtlas supports exact lookup and ranked search, immutable typed models, Unicode local names and flag emoji, WGS84 coordinates, distance/bearing/midpoint calculations, deterministic samples and flashcards, land-border paths, profile filters, physical-feature searches, rankings, and nearest-capital queries. Public results serialize to JSON-compatible dictionaries without losing their source context.

Educational scope

PyWorldAtlas provides offline factual geography for education and reference. It does not provide political commentary or opinion. Values follow documented source conventions, missing data remains explicit, and every field family has a defined source role and publication boundary. Read Educational purpose and editorial policy for the formal policy and Data sources and freshness for exact provenance.

Install

python -m pip install --upgrade pyworldatlas

The current source checkout can be installed with python -m pip install -e ..