Zipcodes: Query U.S. State Zipcodes

Warnings

• gotcha This library bundles its U.S. zipcode data directly within the package. While this avoids external database dependencies (like SQLite), users should be aware that data freshness depends on new package releases. The latest dataset update was February 16, 2025 (v1.3.0).
  Fix: Ensure you are using the latest version of the `zipcodes` library to benefit from the most recent dataset updates. Update with `pip install --upgrade zipcodes`.
• gotcha The `zipcodes` library is distinct from other similarly named Python packages like `uszipcode` or `pyzipcode`. This library explicitly states it does not require the `sqlite3` module, unlike some alternatives. Ensure you are importing and using the correct library for your needs.
  Fix: Verify your `import` statements and package documentation to confirm you are interacting with the `zipcodes` library (from `github.com/seanpianka/zipcodes`) if that is your intention.
• gotcha The library is designed for U.S. zip codes only. It does not provide functionality for international postal codes. Attempting to query non-U.S. zip codes will likely result in no matches or errors.
  Fix: For international postal code lookups, consider libraries or APIs specifically designed for global geocoding or country-specific postal data.

Install

• pip install zipcodes Install stable version

Imports

• zipcodes

  import zipcodes

Quickstart

Demonstrates basic usage including checking if a zipcode is real, getting exact matches, filtering by city/state, and finding similar zipcodes.

import zipcodes
from pprint import pprint

# Check if a zipcode is real
assert zipcodes.is_real('77429')
print(f"Is 77429 a real zipcode? {zipcodes.is_real('77429')}")

# Get exact matches for a zipcode
exact_zip = zipcodes.matching('77429')[0]
print("\nExact match for 77429:")
pprint(exact_zip)

# Filter by city and state
filtered_zips = zipcodes.filter_by(city="Cypress", state="TX")
print(f"\nNumber of zipcodes in Cypress, TX: {len(filtered_zips)}")

# Find similar zipcodes (e.g., by prefix)
similar_zips = zipcodes.similar_to('7742')
print(f"\nNumber of zipcodes similar to '7742': {len(similar_zips)}")