PyZipCode

Common errors

• sqlite3.h: No such file or directory

  cause Missing SQLite development headers required to compile the underlying pysqlite dependency.
  fix Install SQLite development libraries. On Debian/Ubuntu: `sudo apt-get install libsqlite3-dev`. On Fedora/RHEL: `sudo yum install sqlite-devel` or `sudo dnf install sqlite-devel`.

• KeyError: 'Some_Missing_ZipCode'

  cause The requested zip code is not found in the local database. This can happen if the zip code is new or if the underlying data is incomplete/outdated.
  fix Wrap zip code lookups in a `try-except KeyError` block to gracefully handle missing entries. For more comprehensive and up-to-date data, consider alternative libraries or services. Example: `try: zipcode = zcdb['10013'] except KeyError: print('Zip code not found.')`.

• AttributeError: 'ZipCode' object has no attribute 'city' (or similar for other attributes)

  cause While less common in current versions, some users reported issues where certain attributes like 'city' were unexpectedly empty or missing for valid zip codes. This could be due to data inconsistencies or an older version of the underlying database.
  fix Verify the `ZipCode` object's attributes using `dir(zipcode_object)` to see available fields. If an attribute is consistently missing for known valid zip codes, consider refreshing the database if the library provides such a mechanism, or switching to an alternative library like `uszipcode` for potentially richer and more reliable data.

Warnings

• gotcha The underlying zip code data is based on older datasets (e.g., US Census Bureau from 1999-2000, Maxmind Cities DB, or pablotron.org from 2004) and is not actively updated. This can lead to missing newer zip codes or outdated information for existing ones.
  Fix: For the most up-to-date zip code data, consider alternative libraries like `uszipcode` (if available for your use case) or commercial APIs that maintain current datasets.
• breaking Older versions (pre-1.0 and pre-Python 3 compatibility) of `pyzipcode` had different import paths (e.g., `import.py` module) and handled zip codes as integers. The current `3.x` series is Python 3 compatible and expects string inputs for zip codes where appropriate.
  Fix: Ensure you are using `from pyzipcode import ZipCodeDatabase`. Always pass zip codes as strings to `zcdb['ZIPCODE']` or `zcdb.get_zipcodes_around_radius('ZIPCODE', radius)` to avoid unexpected behavior or errors. Use `pip install pyzipcode` to get the latest Python 3 compatible version.
• gotcha On some Linux or non-standard environments, the installation of `pyzipcode` might fail due to missing SQLite development headers required for `pysqlite`. This manifests as errors related to `sqlite3.h` not found.
  Fix: Install the SQLite development package for your system before running `pip install pyzipcode`. For Debian/Ubuntu: `sudo apt-get install libsqlite3-dev`. For Fedora/RHEL: `sudo yum install sqlite-devel` or `sudo dnf install sqlite-devel`.

Install

• pip install pyzipcode Install PyZipCode

Imports

• ZipCodeDatabase

  from pyzipcode import ZipCodeDatabase

Quickstart

Initializes the ZipCodeDatabase and demonstrates basic lookups by zip code, searching by city, and finding zip codes within a geographical radius.

from pyzipcode import ZipCodeDatabase

zcdb = ZipCodeDatabase()

# Lookup a specific zip code
try:
    zipcode_entry = zcdb['10013']
    print(f"Zip: {zipcode_entry.zip}, City: {zipcode_entry.city}, State: {zipcode_entry.state}, Lat: {zipcode_entry.latitude}, Lng: {zipcode_entry.longitude}")
except KeyError:
    print("Zip code not found.")

# Find zip codes by city
manhattan_zips = zcdb.find_zip(city='Manhattan')
print(f"\nZip codes in Manhattan: {[z.zip for z in manhattan_zips[:5]]}...")

# Get zip codes around a radius
zipcodes_in_radius = zcdb.get_zipcodes_around_radius('90210', 10)
print(f"\nZip codes within 10 miles of 90210: {[z.zip for z in zipcodes_in_radius[:5]]}...")