{"id":4952,"library":"geonamescache","title":"Geonames Cache","description":"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.","status":"active","version":"3.0.1","language":"en","source_language":"en","source_url":"https://github.com/yaph/geonamescache","tags":["geography","data","cities","countries","continents","US states","ISO codes","FIPS codes","geo"],"install":[{"cmd":"pip install geonamescache","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false},{"reason":"Required for typing support.","package":"typing-extensions","optional":false}],"imports":[{"symbol":"GeonamesCache","correct":"from geonamescache import GeonamesCache"}],"quickstart":{"code":"from geonamescache import GeonamesCache\n\ngc = GeonamesCache(min_city_population=1000)\n\ncontinents = gc.get_continents()\nprint(f\"Number of continents: {len(continents)}\")\n\ncountries = gc.get_countries()\nprint(f\"Number of countries: {len(countries)}\")\n\ncities = gc.get_cities()\nprint(f\"Number of cities (min_population=1000): {len(cities)}\")\n\n# Example: Get data for a specific country (Spain)\nspain_data = gc.get_countries().get('ES')\nif spain_data:\n    print(f\"\\nSpain data: {spain_data['name']} (Population: {spain_data.get('population')})\")\n\n# Example: Search for cities by name\nlondon_cities = gc.search_cities('London')\nprint(f\"\\nFound {len(london_cities)} cities named 'London':\")\nfor city in london_cities[:3]: # Print first 3 results\n    print(f\"- {city['name']}, {city['countrycode']} (Population: {city['population']})\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade to Python 3.10 or newer to use current versions of the library.","message":"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+.","severity":"breaking","affected_versions":"<1.3.0 for Python 2.x users, <3.0.0 for Python <3.10 users"},{"fix":"Ensure you are using `geonamescache` version 3.0.1 or newer, especially if running on Python 3.11, 3.12, or 3.13.","message":"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.","severity":"gotcha","affected_versions":"<3.0.1 (on Python >=3.11)"},{"fix":"Upgrade to `geonamescache` version 1.5.0 or later to ensure data loading works correctly on Python 3.8.","message":"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`.","severity":"gotcha","affected_versions":"<1.5.0 (on Python 3.8)"},{"fix":"Instantiate `GeonamesCache` with `gc = GeonamesCache(min_city_population=X)` where X is your desired minimum population (500, 1000, 5000).","message":"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).","severity":"gotcha","affected_versions":"All versions >=1.4.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}