geonamescache

What it is and what it does

GeonamesCache wraps geographic reference data from GeoNames into a Python library, letting you query continents, countries, US states, counties, and cities as dictionaries. It includes country codes, state and county codes, population figures, and geographic coordinates. The library loads data into memory on initialization, then provides lookup and search methods to retrieve records by code, name, or partial match.

You'd use it when you need reliable geographic identifiers and metadata in your application—mapping user input to country codes, validating state abbreviations, finding cities by name, or building reference data for location-based features. It's a reference library rather than a mapping or geocoding service; it doesn't convert addresses to coordinates or vice versa, but it does provide the canonical codes and names you'd use alongside such services.

Use it for:

• Validate and normalize country or state codes in user input or data imports.
• Build dropdown menus or autocomplete for location selection in web forms.
• Map city names to population and geographic coordinates for analytics or filtering.
• Create reference lookups for codes in data pipelines.
• Search for cities by partial name match across the dataset.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides Python dictionaries of geographic data including continents, countries, US states, counties, and cities with names, ISO and FIPS codes, population, and coordinates sourced from GeoNames.

Yes. It's a lightweight, actively maintained reference library with no security vulnerabilities, permissive licensing, and a narrow, well-defined purpose. Install it if you need reliable geographic codes and names; skip it if you need real-time geocoding or mapping services.

Install

geonamescache on PyPI

pip install geonamescache

uv add geonamescache

poetry add geonamescache

Installing geonamescache

Before you install

Low friction install with a single lightweight dependency (typing-extensions). Actively maintained with a recent release 17 days ago and continuous repository activity.

License in practice

MIT license permits commercial and private use with minimal restrictions, making it safe for most projects.

Quickstart

pip install geonamescache

import geonamescache

gc = geonamescache.GeonamesCache()
countries = gc.get_countries()
print(countries)

Requires Python 3.10 or later.

Verify before relying

• Whether the bundled GeoNames dataset is updated regularly or requires manual refresh.
• Performance characteristics when searching across large city datasets.
• Memory footprint when loading all cities at minimum population threshold.
• Specific ISO and FIPS code standards covered by the dataset.

Package facts

Evidence: geonamescache-3.0.2-py3-none-any.whl

Keywords: counties, countries, fips, geo, geodata, geonames, iso-codes, states

Tags

More Python Modules packages