pyzipcode

library3.0.1pypypi✓ verified 87d ago

PyZipCode is a Python library designed to query zip code and location data. It uses a local SQLite database, typically derived from sources like Maxmind Cities DB or older Census Bureau data, to provide information such as city, state, latitude, longitude, timezone, and daylight savings time flag for US zip codes. The current stable version is 3.0.1, last released in March 2021, and it supports Python 3.6+. Releases are infrequent but address compatibility and bug fixes.

database

pip install pyzipcode

github ↗package ↗

INSTALL

IMPORT

SIG · PYZIPCODE

pyzipcode

databasepythonv3.0.1

Install

2.7s avg

Import

12ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.013s · 23.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.7s · import 0.012s · 24MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ZipCodeDatabase

✓ from pyzipcode import ZipCodeDatabase

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]]}...")

Debug

Known issues

gotchaThe 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.

affects: All versions

breakingOlder 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.

affects: < 3.0.0

gotchaOn 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`.

affects: All versions (during installation)

Errors

Common errors & fixes

sqlite3.h: No such file or directory

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'

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)

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.

Upgrade

Version history

3.0.1latest on PyPI · released Mar 3, 2021

Audit

Dependencies

sqlite3requiredUsed for the local zip code database. While often built-in with Python, development headers (e.g., `sqlite-devel` on Linux) may be required on some systems for successful installation or if building from source.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/vangheem/pyzipcode ↗

packagehttps://pypi.org/project/pyzipcode/ ↗