US Zipcode Programmable Database

1.0.1 · active · verified Sun Apr 12

uszipcode is a Python library providing a programmable database for USA zip codes, including 2020 census data and geometry information. It offers a powerful and user-friendly search engine to query zip code data. The current version is 1.0.1, and the project maintains an active release cadence with regular updates.

Warnings

breaking Version 1.0.1 and later explicitly drops support for Python 2.7. The library now requires Python 3.6 or later.
Fix: Ensure your project runs on Python 3.6+ and upgrade your Python environment if necessary.
breaking A recent update to the `sqlalchemy-mate` dependency (version 2.0.0.1) caused a breaking change, moving the `ExtendedBase` attribute. This can lead to `ModuleNotFoundError` when importing `uszipcode`.
Fix: As a workaround, pin `sqlalchemy-mate` to an earlier compatible version, specifically `sqlalchemy-mate==2.0.0.0` or older, in your `requirements.txt` or `pip install` command.
gotcha By default, `SearchEngine()` uses the `SimpleZipcode` database (approx. 10MB) which contains basic information. For more comprehensive data points (e.g., population density, income, education), you must explicitly request the `ComprehensiveZipcode` database (approx. 450MB).
Fix: Initialize `SearchEngine` with `simple_or_comprehensive=SearchEngine.SimpleOrComprehensiveArgEnum.comprehensive` to access the richer dataset. Be aware of the larger download size.
gotcha The data provided, while including 2020 census data for some demographic statistics over time, still relies on Census 2010 for general population and income data. The author explicitly states a disclaimer regarding data accuracy.
Fix: Users should be aware of potential data freshness limitations and verify critical data points with official sources for applications requiring the latest accuracy.
gotcha `ModuleNotFoundError` for `uszipcode` despite successful installation is commonly caused by multiple Python installations or conflicting virtual environments, leading to `pip` installing in one environment while the script runs in another.
Fix: Ensure you are using the `pip` executable associated with the Python interpreter running your script (e.g., `python -m pip install uszipcode`) or activate the correct virtual environment.

Install

pip install uszipcode Install stable version

Imports

SearchEngine
```
from uszipcode import SearchEngine
```
ZipcodeSearchEngine
```
from uszipcode import SearchEngine
```
This class was used in older versions (e.g., 0.x) but has been renamed to `SearchEngine` in current versions (1.x).

Quickstart

Initialize the `SearchEngine` to interact with the US zip code database. The database will be downloaded automatically upon first use. You can then use methods like `by_zipcode` or `by_city_and_state` to retrieve detailed information.

from uszipcode import SearchEngine

# Initialize the search engine (downloads database on first run)
search = SearchEngine()

# Search by a specific zip code
zipcode = search.by_zipcode("10001")

if zipcode:
    print(f"Zip Code: {zipcode.zipcode}")
    print(f"City: {zipcode.major_city}")
    print(f"State: {zipcode.state}")
    print(f"Population: {zipcode.population}")
    print(f"Latitude: {zipcode.lat}, Longitude: {zipcode.lng}")
else:
    print("Zip code not found.")

# Example: Search by city and state
zipcodes_in_city = search.by_city_and_state(city="New York", state="NY")
print(f"\nFound {len(zipcodes_in_city)} zip codes in New York, NY.")
if zipcodes_in_city:
    print(f"First zip code: {zipcodes_in_city[0].zipcode}")

view raw JSON →