{"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":"python","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,"search_vec":"'1.0.1':44 '2020':19 'activ':50 'cadenc':52 'census':20,58 'code':17,38 'current':41 'data':21,39,59 'databas':4,13 'engin':34 'friend':32 'geometri':23 'geospati':57 'includ':18 'inform':24 'librari':9 'locat':61 'maintain':48 'offer':26 'power':28 'programm':3,12 'project':47 'provid':10 'python':8 'queri':36 'regular':54 'releas':51 'search':33 'updat':55 'us':1 'usa':15 'user':31 'user-friend':30 'uszipcod':5 'util':60 'version':42 'zip':16,37 'zipcod':2,56","created_at":"2026-04-12T08:54:21.599132+00:00","updated_at":"2026-04-17T14:56:41.428664+00:00","problems":{"verify_error":"/tmp/tmpk70q6d6c/venv/lib/python3.12/site-packages/fuzzywuzzy/fuzz.py:11: UserWarning: Using slow pure-python SequenceMatcher. Install python-Levenshtein to remove this warning\n  warnings.warn('Using slow pure-python SequenceMatcher. Install python-Levenshtein to remove this warning')\nTraceback (mos"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.0.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/uszipcode/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-09","install_tag":null}}