{"id":7648,"library":"pyzipcode","title":"PyZipCode","description":"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.","status":"active","version":"3.0.1","language":"en","source_language":"en","source_url":"https://github.com/vangheem/pyzipcode","tags":["zipcode","location","geocoding","data","sqlite"],"install":[{"cmd":"pip install pyzipcode","lang":"bash","label":"Install PyZipCode"}],"dependencies":[{"reason":"Used 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.","package":"sqlite3","optional":false}],"imports":[{"symbol":"ZipCodeDatabase","correct":"from pyzipcode import ZipCodeDatabase"}],"quickstart":{"code":"from pyzipcode import ZipCodeDatabase\n\nzcdb = ZipCodeDatabase()\n\n# Lookup a specific zip code\ntry:\n    zipcode_entry = zcdb['10013']\n    print(f\"Zip: {zipcode_entry.zip}, City: {zipcode_entry.city}, State: {zipcode_entry.state}, Lat: {zipcode_entry.latitude}, Lng: {zipcode_entry.longitude}\")\nexcept KeyError:\n    print(\"Zip code not found.\")\n\n# Find zip codes by city\nmanhattan_zips = zcdb.find_zip(city='Manhattan')\nprint(f\"\\nZip codes in Manhattan: {[z.zip for z in manhattan_zips[:5]]}...\")\n\n# Get zip codes around a radius\nzipcodes_in_radius = zcdb.get_zipcodes_around_radius('90210', 10)\nprint(f\"\\nZip codes within 10 miles of 90210: {[z.zip for z in zipcodes_in_radius[:5]]}...\")","lang":"python","description":"Initializes the ZipCodeDatabase and demonstrates basic lookups by zip code, searching by city, and finding zip codes within a geographical radius."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"< 3.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions (during installation)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"Missing SQLite development headers required to compile the underlying pysqlite dependency.","error":"sqlite3.h: No such file or directory"},{"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.')`.","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.","error":"KeyError: 'Some_Missing_ZipCode'"},{"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.","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.","error":"AttributeError: 'ZipCode' object has no attribute 'city' (or similar for other attributes)"}]}