Quickstart

Install PyWorldAtlas, open one atlas, and ask useful geography questions. The package works from its bundled database, so these examples need no API key or runtime network connection.

Install

python -m pip install pyworldatlas

Check the installation

The installed command offers quick lookups without writing a Python file:

pyworldatlas --version
pyworldatlas country Japan
pyworldatlas search guinea

Use pyworldatlas --help to see every command, from find and near to sun and stat. The command and the Python API read the same bundled database and work offline after installation.

Meet a country

Use Atlas as a context manager and look up a country by name or standard code:

>>> from pyworldatlas import Atlas
>>> with Atlas() as atlas:
...     brazil = atlas.country("BR")
...     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]))
🇧🇷 Brasil | Brasília
Pico da Neblina 2,994 m
Amazon, Río de la Plata/Paraná, Tocantins

country returns an immutable, typed profile. Facts stay available as attributes, while summary() provides a readable introduction for a terminal, notebook, or lesson:

with Atlas() as atlas:
    print(atlas.country("Dominican Republic").summary)

Explore the world in five minutes

Every install can search 200,000 places, work out the sun anywhere, and dig through the Earth:

>>> from datetime import date
>>> with Atlas() as atlas:
...     everest = atlas.search_places("Everest", limit=1)[0]
...     print(everest, "|", everest.elevation_m, "m")
...     print(atlas.sun("Oslo", date(2026, 12, 21)).daylight, "of daylight in Oslo at midwinter")
...     print(atlas.antipode("Madrid").nearest[0].place.country_code)
Mount Everest, mountain (NP) | 8848 m
5 h 54 min of daylight in Oslo at midwinter
NZ

Optional packs add more, each with one command: pyworldatlas get statistics for World Bank numbers since 1960 (The world in numbers), pyworldatlas get landmarks for airports and World Heritage sites (Airports and World Heritage), and pyworldatlas get maps for 3D maps (Interactive 3D maps).

Look up, search, and collect

Names, aliases, alpha-2, alpha-3, and M49 codes resolve to the same profile. The atlas also behaves like a normal Python collection:

>>> with Atlas() as atlas:
...     print(atlas.country("Japan") == atlas.country("JPN"))
...     print(atlas["DO"].capital.name)
...     print([match.country.name for match in atlas.search_countries("guinea")[:3]])
...     print(len(atlas.countries(continent="Europe")))
True
Santo Domingo
['Guinea', 'Guinea-Bissau', 'Equatorial Guinea']
51

Combine facts with geography

The same API connects country profiles, cities, coordinates, distances, rankings, and reviewed land neighbors:

>>> with Atlas() as atlas:
...     japan = atlas.country("Japan")
...     print(japan.anthem.title)
...     print(japan.climate.dominant_zone.code)
...     print(round(atlas.distance_between("Tokyo", "Paris", first_country="JP", second_country="FR")))
...     print([country.alpha2 for country in atlas.neighbors("Brazil")[:4]])
Kimigayo
Cfa
9713
['AR', 'BO', 'CO', 'GF']

What to remember

  • Use with Atlas() as atlas so the read-only database closes promptly.

  • Missing scalar facts are None and missing collections are empty. The package does not invent values to fill source gaps.

  • Results are typed Python objects. Use to_dict() when you need portable, JSON-compatible data.

  • dataset_info() reports the installed library, schema, and dataset versions.

Where to go next