PyWorldAtlas: offline world geography for Python

Offline country profiles, physical geography, optional 3D maps, distances, and learning tools for Python.

248 profiles · 248 optional 3D maps · 6,265 populated places · 0 core runtime dependencies

Documentation · Quickstart · Playground · 3D maps · Examples · API reference

No installation needed: open the browser playground and run the guided Python examples.

PyWorldAtlas is an offline world-geography Python package built around one bundled, source-aware database. It turns country profiles, physical geography, cities, distances, borders, optional 3D maps, and learning tools into ordinary Python objects for developers, classrooms, and curious learners. No API key is required, and installed features work offline.

Iceland rendered by the Standard map edition with elevation, coastline, Reykjavík, a river overlay, and source notes. Select the image for the map guide.

Install

python -m pip install --upgrade pyworldatlas

PyWorldAtlas supports Python 3.10 through 3.14. The installed package works offline and has no third-party runtime dependencies.

Add the recommended global 3D map edition when you want interactive terrain:

python -m pip install --upgrade "pyworldatlas[maps]"

Use pyworldatlas[maps-overview] for the smaller Overview edition. Map data is optional and never enlarges the ordinary package installation.

Meet a country

from pyworldatlas import Atlas

with Atlas() as atlas:
    brazil = atlas.country("Brazil")
    print(brazil.summary())

🇧🇷 Brazil · Brasil
Formal name: Federative Republic of Brazil
Capital: Brasília
Location: Americas · South America
Population snapshot: 209,469,333
Currency: Brazilian Real (BRL, R$)
Languages: English (en), Spanish (es), French (fr), Portuguese (pt-BR)
Anthem title: Hino Nacional Brasileiro · Brazilian National Anthem
Motto: Ordem e Progresso · Order and Progress
Highest point: Pico da Neblina (2,994 m)
Dominant climate class: Aw · Tropical, savannah
Source-listed rivers: Amazon, Río de la Plata/Paraná, Tocantins
Source-listed lakes: Lagoa dos Patos, Lagoa Mirim

Atlas opens a bundled, read-only SQLite database. Results are immutable, typed models rather than loosely structured dictionaries, and loaded records remain usable after the atlas is closed.

Open the terrain

from pyworldatlas import Atlas

with Atlas() as atlas:
    atlas.map("Iceland").show()

The one-line call opens a local, rotatable 3D map in the default browser with elevation, Köppen-Geiger climate coloring, rivers, the country outline, and the primary capital. The viewer and data remain offline after installation. Use atlas.map("Iceland").write_html("iceland-map.html") to create a standalone document for a lesson or presentation.

Compare the map editions and learn the API.

What you can explore

Explore with small, readable programs

Look up countries by familiar name or standard code:

with Atlas() as atlas:
    assert atlas.country("Japan") == atlas.country("JP")
    assert atlas.country("JPN") == atlas.country("392")
    print(atlas.country("Japan").name_in("ja"))

Measure and connect places:

with Atlas() as atlas:
    tokyo = atlas.city("Tokyo", country="JP")
    paris = atlas.city("Paris", country="FR")

    print(tokyo.coordinates.format())
    print(tokyo.coordinates.dms())
    print(f"{atlas.distance_between(tokyo, paris):,.0f} km")
    print(tokyo.coordinates.compass_direction_to(paris.coordinates))

    nearby = atlas.nearest_cities(tokyo, within_country="JP", limit=3)
    print([result.city.name for result in nearby])

    route = atlas.border_path("Portugal", "China")
    print(" → ".join(route.names))

Build a repeatable lesson:

with Atlas() as atlas:
    questions = atlas.quiz(topic="local_names", count=5, seed=42)

    for question in questions:
        print(question.prompt)
        for number, choice in enumerate(question.choices, 1):
            print(f"  {number}. {choice}")
        print("Answer:", question.answer_number)

Distances are great-circle surface measurements, not road or flight routes. Border paths use the reviewed land-border graph and do not infer maritime or boundary geometry.

Built for learning

• Offline: lessons and programs do not depend on an external service.
• Repeatable: seeded samples, flashcards, and quizzes produce stable results.
• Source-aware: provenance and coverage limits are documented.
• Beginner-friendly: common tasks use small Python objects and methods.
• Honest about missing data: unavailable values remain None or empty tuples.

The project provides factual geography and transparent calculations, not political commentary or opinion. Read the educational and neutrality policy for the formal publication standard.

Coverage at a glance

Library 0.9.1 includes dataset 2026.07.22.7 and schema 7.

See the generated project status for complete coverage and data quality for interpretation limits.

Data and trust

Field families use defined source roles rather than one unreviewed compilation. The builder retains source snapshots, checksums, review decisions, and exact coverage gates. Sources include United Nations M49, GeoNames, Unicode CLDR, UNGEGN, Natural Earth, the CIA World Factbook, Wikidata, IANA registries, and the Beck et al. Köppen-Geiger dataset, and NOAA NCEI ETOPO 2022.

• Data sources and freshness
• Data quality and limitations
• Educational purpose and editorial policy
• Third-party notices

Documentation and community

• Run Python in the browser
• Try the classroom-friendly learning lab
• Browse complete recipes
• Read the country-profile guide
• Explore physical geography
• Open interactive 3D maps
• Review the API
• See the roadmap

Questions, factual corrections, documentation improvements, and focused code contributions are welcome. Start with CONTRIBUTING.md, follow the code of conduct, and report security concerns through SECURITY.md.

Development

python maintain.py bootstrap
python maintain.py check

maintain.py check runs tests, builds the core and optional-map distributions, installs the wheels in isolation, renders an offline map, executes examples, builds strict documentation and doctests, and audits the release contents.

License

PyWorldAtlas code is available under the MIT License. Bundled data retains its original terms and attribution; see THIRD_PARTY_NOTICES.md.