Every place on Earth

Find any named place: towns, mountains, volcanoes, lakes, rivers, deserts, islands, ruins, castles, and more. Every install includes the school atlas of about 200,000 places, chosen by educational value, and two optional packs add every other place in the GeoNames gazetteer. All searches run offline.

In 30 seconds

>>> from pyworldatlas import Atlas
>>> with Atlas() as atlas:
...     print(atlas.search_places("Machu Picchu", limit=1)[0])
...     print(atlas.places_near((48.8584, 2.2945), limit=1)[0].place)
Machu Picchu, ruins (PE)
Eiffel Tower, monument (FR)

>>> from pyworldatlas import Atlas
>>> atlas = Atlas()
>>> fuji = atlas.place("Mount Fuji")
>>> fuji.name, fuji.kind, fuji.country_code
('Fujiyama', 'volcano', 'JP')
>>> str(atlas.place("Lake Titicaca"))
'Lake Titicaca, lake (BO)'

Searching by name

search_places() matches local and English names, ignores case and accents, and puts the best-known places first. A place can be found without its generic first or last word, so "Everest" finds Mount Everest before the town of Everest, Kansas.

>>> [str(place) for place in atlas.search_places("Everest", limit=2)]
['Mount Everest, mountain (NP)', 'Everest, town (US)']
>>> [str(place) for place in atlas.search_places("Kilimanjaro", limit=2)]
['Mount Kilimanjaro, mountain (TZ)', 'Kilimanjaro, state or province (TZ)']

place() returns the single best-known place with exactly that name. Narrow any search with kind (see place_kinds()), category ("water", "landform", "town", "landmark", …), or country.

>>> [place.country_code for place in atlas.search_places("Paris", country="France", limit=2)]
['FR', 'FR']
>>> atlas.search_places("Fuji", kind="volcano", limit=1)[0].english_name
'Mount Fuji'

One search for everything

find() searches countries and places together, for a search box that accepts anything. A country named exactly comes first as its full profile, then the best-known places.

>>> [str(item) for item in atlas.find("Luxembourg", limit=2)]
['Luxembourg', 'Luxembourg, capital city (LU)']
>>> atlas.find("Luxembourg")[0].capital.name
'Luxembourg'

The best-known places in a country

places_in() lists a country’s best-known places, narrowed by kind or category when wanted. 3D maps mark these places (see Interactive 3D maps).

>>> [place.english_name for place in atlas.places_in("Iceland", kind="volcano", limit=2)]
['Hekla', 'Laki']

What is near here?

places_near() lists the nearest places to any city, place, country, or coordinate. The answer is exact: the search widens until no closer place can exist.

>>> nearest = atlas.places_near((48.8584, 2.2945), limit=1)
>>> str(nearest[0].place)
'Eiffel Tower, monument (FR)'
>>> [result.place.category for result in atlas.places_near("Nairobi", category="water", limit=3)]
['water', 'water', 'water']
>>> atlas.close()

What is in the school atlas

Places are ranked by educational value using only signals in the data: what a place is, how big or high it is, and how widely it is known (named in other writing systems and languages, with an English Wikipedia article). The school atlas holds:

every country, territory, state, and province, every capital and regional seat, the continents, oceans, and seas;
every town of 5,000 people or more, and smaller towns that are widely known;
every peak over 6,000 m, and mountains, volcanoes, lakes, rivers, deserts, islands, and forests that are widely known;
ruins, castles, monuments, museums, and other landmarks named across cultures.

A short reviewed list keeps famous places whose source entries lack those signals, such as the Grand Canyon and the Sahara.

More places with packs

Two optional packs add everything else, so nothing is left out for those who want it. Each pack adds to the ones before it.

Pack	Adds	Download
school atlas (built in)	about 200,000 places	included
`places-explorer`	every town over 1,000 people and every named natural feature, about 3.3 million places	about 23 MB
`places-world`	every remaining village, stream, hill, and local area, about 7.6 million places	about 44 MB

pyworldatlas get places-explorer places-world

Installed packs are searched automatically. Shops, hotels, farms, roads, and similar spots are not included in any edition.

The command line has the same searches:

pyworldatlas find Luxembourg
pyworldatlas place "Lake Titicaca"
pyworldatlas near -3.0674 37.3556 --kind peak

How it stays small and fast

Each place takes 6 to 10 bytes. Places are ordered along a Hilbert curve so neighbours sit together, stored column by column as small varint differences, and compressed with LZMA or bz2, all with the Python standard library. The first search unpacks the data once into a SQLite index in the pack folder; later searches take under a millisecond, and nearest-place lookups a few milliseconds.

Edition	First search on a laptop (once)	Disk space once unpacked
school atlas	about 2 seconds	about 25 MB
with `places-explorer`	about 25 seconds more	about 320 MB more
with `places-world`	about 55 seconds more	about 710 MB more

Coordinates are rounded to about 110 m and are not suitable for navigation. Place data comes from GeoNames under CC BY 4.0; see Data sources and freshness.