census-geocoding

Find the most populous municipalities near a given U.S. city using a local USZipcode SQLite database.

City/state lookups use a full-text search (FTS5) table for fuzzy matching. The haversine formula filters municipalities to those within a given radius, and the results are ranked by population (most populous first).

Requirements

• Python >= 3.13
• The USZipcode simple database at data/uszipcode_simple.sqlite (from the uszipcode-project release).

Usage

The included database already has the zipcode_lookup full-text search table built, so no setup is required. Run the example, which finds the 10 most populous municipalities within 20 miles of Bedford, NH:

python main.py

Files

• main.py — city/state lookups, radius search, and the haversine great-circle distance function.
• scripts/create_zip_lookup_table.py — illustrates how the zipcode_lookup FTS5 virtual table was built from the simple_zipcode table (not needed to run the example).
• data/uszipcode_simple.sqlite — the zip code database, including the prebuilt zipcode_lookup table.