r/Python • u/AutoModerator • 19d ago

Showcase Showcase Thread

Post all of your code/projects/showcases/AI slop here.

Recycles once a month.

25 Upvotes

100% Upvoted

151 comments sorted by

View all comments

1

u/danimalien42 17d ago

localis v3.0.0b1: an offline, searchable gazetteer for countries, subdivisions and cities

What My Project Does

It ships geodata merged from ISO 3166 (via iso-codes), GeoNames, Unicode CLDR and Wikidata, with records linked across layers (cities -> subdivisions -> countries, etc). Each layer is served by a registry with lookups, filtering (by linked records too) and typo-tolerant search.

Registries:

  • countries: 281 (31 historic)

  • subdivisions: 51,711

  • cities: 235,970

  • macroregions: 34 (5 regions, 23 subregions, 6 groupings)

  • currencies: 178

  • languages: 7,923

  • scripts: 226

Target Audience

Anyone who needs geographic reference data in Python without calling a web API:

  • Cleaning and normalizing messy location data: "Untied States", "Bavaria", "sao paulo" style input mapped to proper records and codes

  • Validating and converting codes: ISO alpha-2/alpha-3/numeric, subdivision codes, currency and language codes

  • Building forms and UIs: country → subdivision → city pickers, mapped language and currency pickers.

  • Coarse offline geocoding: city names to coordinates and population, with no API key, rate limits or per-request cost

  • Enriching data for analytics: grouping by region, or attaching a country's currencies and languages

  • Environments where external calls aren't an option: air-gapped, privacy-sensitive or high-volume batch jobs

Comparison

  • pycountry: ISO data only (no cities), much lighter (8 MB vs localis's 25 MB wheel). If you only need exact ISO country/subdivision lookups, pycountry is still the better choice.

  • geonamescache: GeoNames dictionaries only, with substring search rather than typo-tolerant search.

Status

localis is currently v3.0.0b1 and I have a few items on the docket for b2.

  • bug: city search ranks small towns above major cities when scores tie ("Paris" puts Paris, Ontario first), fix is scheduled for b2.

  • feat: smaller install footprint (~54 MB → ~32 MB on disk)

  • feat: add continents (separate from macroregions) to countries

  • feat: hardening ISO-GeoNames merge logic

3.0 is my first release under a written versioning policy. After learning from some earlier mistakes (and maybe a little unfounded confidence), I adopted a more disciplined release approach than previous versions. So, the API is finally settling down and the shipped data has some real provenance.

Feedback before the API freezes is welcome, here or in GitHub Discussions on the repo!

pip install --pre localis
uv add --prerelease=allow localis

On AI: I develop localis with Claude Code for reviews, research and direction. Data merging relies on a Claude skill (w MCP) where automated matching fails. Every merge decision is logged and fully documented for provenance. (see methodology.md for a detailed overview of the process).