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 --upgrade pyworldatlas

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())

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