Geonames Cache

3.0.1 · active · verified Sun Apr 12

geonamescache is a Python library that provides quick access to a subset of GeoNames data. It allows retrieval of names, ISO and FIPS codes for continents, countries, US states, US counties, and cities as Python dictionaries. The country and city datasets also include population and geographic data. The library is actively maintained, with regular updates and a consistent release cadence, including a recent patch release (3.0.1) in March 2026.

Warnings

breaking The `search_cities` function behavior changed significantly in version 2.0.0. It now performs partial, case-insensitive matches by default, which is different from previous versions where list values were treated differently and search was case-sensitive.
Fix: Review calls to `search_cities` and adjust expectations or explicitly set `case_sensitive=True` or `contains_search=False` if exact, case-sensitive matching is needed.
breaking Support for Python 2.7 was dropped in version 1.3.0. The library now requires Python 3.7 or newer. Recent versions (3.0.0+) require Python 3.10+.
Fix: Upgrade to Python 3.10 or newer to use current versions of the library.
gotcha Versions prior to 3.0.1 might encounter a deadlock related to standard library `typing` on Python 3.11+ environments, especially affecting Python 3.13. This was addressed in version 3.0.1.
Fix: Ensure you are using `geonamescache` version 3.0.1 or newer, especially if running on Python 3.11, 3.12, or 3.13.
gotcha The `_load_data` function in versions prior to 1.5.0 used `importlib.resources`, which caused compatibility issues with Python 3.8. This was fixed in version 1.5.0 by switching to `os` and `open`.
Fix: Upgrade to `geonamescache` version 1.5.0 or later to ensure data loading works correctly on Python 3.8.
gotcha When initializing `GeonamesCache`, the `min_city_population` parameter (defaulting to 15000) controls the size of the `cities` dataset. If you need more granular city data (e.g., smaller towns), you must specify a lower `min_city_population` (e.g., 500, 1000, 5000).
Fix: Instantiate `GeonamesCache` with `gc = GeonamesCache(min_city_population=X)` where X is your desired minimum population (500, 1000, 5000).

Install

pip install geonamescache Install latest version

Imports

GeonamesCache
```
from geonamescache import GeonamesCache
```

Quickstart

Initialize GeonamesCache and retrieve data for continents, countries, and cities. The `min_city_population` parameter can be adjusted to include more or fewer cities. Demonstrates how to access specific country data and search for cities by name.

from geonamescache import GeonamesCache

gc = GeonamesCache(min_city_population=1000)

continents = gc.get_continents()
print(f"Number of continents: {len(continents)}")

countries = gc.get_countries()
print(f"Number of countries: {len(countries)}")

cities = gc.get_cities()
print(f"Number of cities (min_population=1000): {len(cities)}")

# Example: Get data for a specific country (Spain)
spain_data = gc.get_countries().get('ES')
if spain_data:
    print(f"\nSpain data: {spain_data['name']} (Population: {spain_data.get('population')})")

# Example: Search for cities by name
london_cities = gc.search_cities('London')
print(f"\nFound {len(london_cities)} cities named 'London':")
for city in london_cities[:3]: # Print first 3 results
    print(f"- {city['name']}, {city['countrycode']} (Population: {city['population']})")

view raw JSON →