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.

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

Install

python -m pip install pyworldatlas

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

Confirm the installation or make a quick terminal lookup:

pyworldatlas --version
pyworldatlas country Japan
pyworldatlas search guinea

The command is a small companion to the Python API. It reads the same bundled database and prints concise messages instead of Python tracebacks for ordinary lookup errors. Run pyworldatlas --help for every command.

Add interactive 3D terrain maps with one command. Maps need no extra Python packages, only their data:

pyworldatlas get maps

Use pyworldatlas get maps-lite for the smaller Overview edition. Packs are checked against fingerprints pinned in the library, and pyworldatlas add FILE installs a copied pack on a machine without internet. To replace an older installation of the package, add --upgrade to the pip command.

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(auto_rotate=True)

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. Adjust terrain height, show every bundled river name, or hide labels for a clean presentation view. Play or pause rotation, adjust its speed, and download a high-resolution PNG of the current angle. The viewer and data remain offline after installation. Use atlas.map("Iceland").write_html("iceland-map.html", auto_rotate=True) to create a standalone rotating 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.10.0 includes dataset 2026.10.26.1 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, 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.