Capitals and major cities

Explore primary capitals and the bundled populated-place collection as typed, coordinate-bearing records. Lookups remain local and require no mapping service.

Capital records

The current snapshot provides 241 primary-capital records for 248 UN M49 countries and areas. The schema supports multiple capitals so later releases can represent administrative, legislative, judicial, and other roles without redesigning the runtime model.

>>> from pyworldatlas import Atlas
>>> atlas = Atlas()
>>> capital = atlas.country("Dominican Republic").capital
>>> capital.name
'Santo Domingo'
>>> capital.coordinates.as_tuple()
(18.47186, -69.89232)
>>> capital.role
'official'
>>> capital.primary
True

Coordinates are signed WGS84 decimal degrees. Positive latitude is north; positive longitude is east.

Missing capitals

Country.capital returns None when the source intersection has no usable capital record. This currently applies to Antarctica, Bouvet Island, British Indian Ocean Territory, Heard Island and McDonald Islands, Tokelau, United States Minor Outlying Islands, and Western Sahara.

>>> atlas.country("Antarctica").capital is None
True

Major cities

The current dataset retains populated places at or above the configured 100,000-person threshold and always retains capitals. Results are ordered by population, then name. The current snapshot contains 6,265 records.

>>> cities = atlas.major_cities("Japan", limit=3)
>>> [city.name for city in cities]
['Tokyo', 'Yokohama', 'Osaka']
>>> cities[0].geonames_id
1850147
>>> atlas.close()

Population values describe the captured source snapshot. They are not live estimates and should not be interpreted as a synchronized census series.

Search city names

Use search_cities() when only part of a place name is known. Exact names rank first, then prefix and substring matches; population breaks ties.

>>> with Atlas() as atlas:
...     matches = atlas.search_cities("santo", country="DO", limit=3)
...     print([city.label for city in matches])
['Santo Domingo (DO)', 'Santo Domingo Oeste (DO)', 'Santo Domingo Este (DO)']

Search returns an empty tuple when no bundled place matches. Use city() when one exact result is required; that method raises a clear missing or ambiguous-place exception instead.

Find nearby cities

nearest_cities() accepts the same origin types as the distance API. within_country can turn it into a local exploration activity:

>>> with Atlas() as atlas:
...     nearby = atlas.nearest_cities(
...         "Santo Domingo",
...         origin_country="DO",
...         within_country="DO",
...         limit=3,
...     )
...     print([(item.city.name, round(item.distance)) for item in nearby])
[('Santo Domingo Este', 5), ('Bella Vista', 6), ('Santo Domingo Oeste', 12)]

Each CityDistance contains a compact country reference, the city record, distance, and unit. Values are great-circle measurements, not road or travel distances.