{"id":4405,"library":"uszipcode","title":"US Zipcode Programmable Database","description":"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.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/MacHu-GWU/uszipcode","tags":["zipcode","geospatial","census","data","utility","location"],"install":[{"cmd":"pip install uszipcode","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used as the underlying ORM for database interactions.","package":"sqlalchemy","optional":false},{"reason":"A dependency that has introduced breaking changes in its 2.0.0.1 release, affecting uszipcode import.","package":"sqlalchemy-mate","optional":false}],"imports":[{"symbol":"SearchEngine","correct":"from uszipcode import SearchEngine"},{"note":"This class was used in older versions (e.g., 0.x) but has been renamed to `SearchEngine` in current versions (1.x).","wrong":"from uszipcode import ZipcodeSearchEngine","symbol":"ZipcodeSearchEngine","correct":"from uszipcode import SearchEngine"}],"quickstart":{"code":"from uszipcode import SearchEngine\n\n# Initialize the search engine (downloads database on first run)\nsearch = SearchEngine()\n\n# Search by a specific zip code\nzipcode = search.by_zipcode(\"10001\")\n\nif zipcode:\n    print(f\"Zip Code: {zipcode.zipcode}\")\n    print(f\"City: {zipcode.major_city}\")\n    print(f\"State: {zipcode.state}\")\n    print(f\"Population: {zipcode.population}\")\n    print(f\"Latitude: {zipcode.lat}, Longitude: {zipcode.lng}\")\nelse:\n    print(\"Zip code not found.\")\n\n# Example: Search by city and state\nzipcodes_in_city = search.by_city_and_state(city=\"New York\", state=\"NY\")\nprint(f\"\\nFound {len(zipcodes_in_city)} zip codes in New York, NY.\")\nif zipcodes_in_city:\n    print(f\"First zip code: {zipcodes_in_city[0].zipcode}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your project runs on Python 3.6+ and upgrade your Python environment if necessary.","message":"Version 1.0.1 and later explicitly drops support for Python 2.7. The library now requires Python 3.6 or later.","severity":"breaking","affected_versions":">=1.0.1"},{"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.","message":"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`.","severity":"breaking","affected_versions":"1.0.1 (when used with sqlalchemy-mate>=2.0.0.1)"},{"fix":"Initialize `SearchEngine` with `simple_or_comprehensive=SearchEngine.SimpleOrComprehensiveArgEnum.comprehensive` to access the richer dataset. Be aware of the larger download size.","message":"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).","severity":"gotcha","affected_versions":"All 1.x versions"},{"fix":"Users should be aware of potential data freshness limitations and verify critical data points with official sources for applications requiring the latest accuracy.","message":"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.","severity":"gotcha","affected_versions":"All 1.x versions"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}