---
id: geonamescache
version: "3.0.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# geonamescache — Geonames data for continents, cities and US states.

License: permissive · Maintenance: active · Downloads: 931.9K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 931.9K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

geographic data lookup, country iso codes, city population data, geonames data python, us states counties, continent country codes, geodata reference, geodata, reference-data, lookup-tables

[View on SkillFed](https://skillfed.io/packages/geonamescache) · [View on PyPI](https://pypi.org/project/geonamescache/)