Rankings and nearby capitals

PyWorldAtlas provides small, composable discovery methods. They return immutable models and never contact a remote service.

Profile filters

Atlas.countries supports exact, case-insensitive profile filters:

atlas.countries(continent="Europe")
atlas.countries(region="Caribbean")
atlas.countries(currency_code="EUR")
atlas.countries(language_code="es")
atlas.countries(script_code="Arab")
atlas.countries(timezone_id="Asia/Tokyo")
atlas.countries(coastal=False)
atlas.countries(koppen_geiger_code="Af")
atlas.countries(has_rivers=True, has_lakes=True)

Multiple arguments are combined with AND. Language values describe the captured GeoNames country metadata; they are not promoted to legal-language claims.

coastal, has_rivers, and has_lakes accept only booleans or None. Physical filters use covered source records: coastal=False means the source reports zero coastline and never turns missing data into a result.

Country rankings

Atlas.rank_countries and its short alias Atlas.rank support these metrics:

Ranking metrics

Metric	Value	Unit
population	Captured country population snapshot	people
area / area_km2	Captured total area	km²
population_density / density	Population divided by total area	people/km²
border_count	Accepted reviewed land-border relationships	countries
major_city_count	Bundled populated-place records	places
land_area / land_area_km2	Source-reported land area	km²
water_area / water_area_km2	Source-reported water area	km²
water_percent	Water area divided by total area	%
coastline / coastline_km	Source-reported coastline length	km
mean_elevation / mean_elevation_m	Source-reported mean elevation	m
highest_elevation / highest_point	Elevation of the named highest point	m
lowest_elevation / lowest_point	Elevation of the named lowest point	m
river_count / lake_count	Number of source-listed major feature records	rivers / lakes
climate_zone_count	Represented Köppen-Geiger classes above the extraction threshold	classes

>>> from pyworldatlas import Atlas
>>> atlas = Atlas()
>>> results = atlas.rank("area", limit=3)
>>> [(row.position, row.country.name, row.unit) for row in results]
[(1, 'Russia', 'km²'), (2, 'Antarctica', 'km²'), (3, 'Canada', 'km²')]
>>> smallest = atlas.rank("density", limit=2, descending=False)
>>> smallest[0].value <= smallest[1].value
True

Rankings are descriptions of bundled values, not judgments about countries or people. Equal values use country name as a stable tie-breaker, and missing values are excluded.

>>> coastlines = atlas.rank("coastline", limit=3)
>>> [(row.country.name, row.value, row.unit) for row in coastlines]
[('Canada', 202080.0, 'km'), ('Indonesia', 54716.0, 'km'), ('Greenland', 44087.0, 'km')]
>>> peaks = atlas.rank("highest_elevation", limit=3)
>>> [(row.country.name, row.value) for row in peaks]
[('China', 8849.0), ('Nepal', 8849.0), ('Pakistan', 8611.0)]

River and lake counts measure source-listed records, not every physical feature. Climate counts depend on the documented 0.1% class-share threshold. See Physical geography before interpreting those metrics.

Nearest capitals

Atlas.nearest_capitals accepts an exact city name, a country, a capital or city object, a Coordinate, or a (latitude, longitude) tuple.

>>> origin = atlas.country("Dominican Republic")
>>> nearest = atlas.nearest_capitals(origin, limit=3)
>>> [(item.capital.name, item.country.alpha2) for item in nearest]
[('Port-au-Prince', 'HT'), ('Cockburn Town', 'TC'), ('San Juan', 'PR')]
>>> nearest[0].unit
'km'
>>> atlas.close()

Distances are spherical great-circle results, not road, air-route, or travel distances. include_origin=False excludes a capital at the origin itself.

"""Filter profiles, rank sourced values, and find nearby capitals."""

from pyworldatlas import Atlas


with Atlas() as atlas:
    yen_profiles = atlas.countries(currency_code="JPY")
    print([country.name for country in yen_profiles])

    for result in atlas.rank_countries("area", limit=5):
        print(result.position, result.country.name, result.value, result.unit)

    for result in atlas.nearest_capitals((18.4861, -69.9312), limit=4):
        print(result.country.name, result.capital.name, round(result.distance), result.unit)