Install & Compatibility
Where this runs
tested against v3.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.018s · 196.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.016s · 197MB
186MB installed
● package 186MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GeonamesCache
✓ from geonamescache import GeonamesCache
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']})")
Debug
Known issues
breakingThe `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.fixReview calls to `search_cities` and adjust expectations or explicitly set `case_sensitive=True` or `contains_search=False` if exact, case-sensitive matching is needed.
affects: >=2.0.0
breakingSupport 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+.fixUpgrade to Python 3.10 or newer to use current versions of the library.
affects: <1.3.0 for Python 2.x users, <3.0.0 for Python <3.10 users
gotchaVersions 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.fixEnsure you are using `geonamescache` version 3.0.1 or newer, especially if running on Python 3.11, 3.12, or 3.13.
affects: <3.0.1 (on Python >=3.11)
gotchaThe `_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`.fixUpgrade to `geonamescache` version 1.5.0 or later to ensure data loading works correctly on Python 3.8.
affects: <1.5.0 (on Python 3.8)
gotchaWhen 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).fixInstantiate `GeonamesCache` with `gc = GeonamesCache(min_city_population=X)` where X is your desired minimum population (500, 1000, 5000).
affects: All versions >=1.4.0
Errors
Common errors & fixes
TypeError: GeonamesCache.get_cities_by_name() missing 1 required positional argument: 'name'
The `get_cities_by_name` method was called without providing the mandatory `name` argument.
fixPass the city name as a string argument to the method, e.g., `gc.get_cities_by_name('London')`. geonamescache search_cities not returning exact match
In `geonamescache` version 2.0.0 and later, the `search_cities` function's default behavior changed to perform partial, case-insensitive matches.
fixTo achieve exact, case-sensitive matching, explicitly set the parameters: `gc.search_cities('Paris', case_sensitive=True, contains_search=False)`. geonamescache get_cities missing small towns
By default, when `GeonamesCache` is initialized, the `min_city_population` parameter is set to 15000, filtering out cities with a population below this threshold.
fixInstantiate `GeonamesCache` with a lower `min_city_population` to include smaller cities, e.g., `gc = GeonamesCache(min_city_population=1000)`.
geonamescache requires python 3.10
Recent versions of `geonamescache` (3.0.0 and above) require Python 3.10 or newer due to compatibility updates.
fixUpgrade your Python environment to version 3.10 or newer, or install an older version of `geonamescache` compatible with your current Python version.
geonamescache deadlock python 3.11
Versions of `geonamescache` prior to 3.0.1 could encounter a deadlock related to the standard library `typing` module when running on Python 3.11, 3.12, or 3.13 environments.
fixUpgrade `geonamescache` to version 3.0.1 or newer to resolve the deadlock issue: `pip install --upgrade geonamescache`.
Upgrade
Version history
3.0.2latest on PyPI · released Jul 28, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
typing-extensionsrequiredRequired for typing support.