.. image:: https://github.com/MacHu-GWU/uszipcode-project/workflows/CI/badge.svg :target: https://github.com/MacHu-GWU/uszipcode-project/actions?query=workflow:CI

.. image:: https://codecov.io/gh/MacHu-GWU/uszipcode-project/branch/master/graph/badge.svg :target: https://codecov.io/gh/MacHu-GWU/uszipcode-project

.. image:: https://readthedocs.org/projects/uszipcode/badge/?version=latest :target: https://uszipcode.readthedocs.io/?badge=latest :alt: Documentation Status

.. image:: https://img.shields.io/pypi/v/uszipcode.svg :target: https://pypi.python.org/pypi/uszipcode

.. image:: https://img.shields.io/pypi/l/uszipcode.svg :target: https://pypi.python.org/pypi/uszipcode

.. image:: https://img.shields.io/pypi/pyversions/uszipcode.svg :target: https://pypi.python.org/pypi/uszipcode

.. image:: https://img.shields.io/pypi/dm/uszipcode :target: https://pypi.python.org/pypi/uszipcode

.. image:: https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social :target: https://github.com/MacHu-GWU/uszipcode-project

---

.. image:: https://img.shields.io/badge/Link-Document-blue.svg :target: https://uszipcode.readthedocs.io/index.html

.. image:: https://img.shields.io/badge/Link-API-blue.svg :target: https://uszipcode.readthedocs.io/py-modindex.html

.. image:: https://img.shields.io/badge/Link-Source_Code-blue.svg :target: https://uszipcode.readthedocs.io/py-modindex.html

.. image:: https://img.shields.io/badge/Link-Install-blue.svg :target: install_

.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg :target: https://github.com/MacHu-GWU/uszipcode-project

.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg :target: https://github.com/MacHu-GWU/uszipcode-project/issues

.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg :target: https://github.com/MacHu-GWU/uszipcode-project/issues

.. image:: https://img.shields.io/badge/Link-Download-blue.svg :target: https://pypi.org/pypi/uszipcode#files

Welcome to uszipcode Documentation

.. contents:: :class: this-will-duplicate-information-and-it-is-still-useful-here :depth: 1 :local:

If you are on www.pypi.org or www.github.com, this is not the complete document. Here is the Complete Document <https://uszipcode.readthedocs.io/index.html>_.

If you are looking for technical support, click the badge below to join this gitter chat room and ask question to the author.

.. image:: https://img.shields.io/badge/Chat-Tech_Support-_.svg :target: https://gitter.im/MacHu-GWU-Python-Library-Technical-Support/community

uszipcode is the most powerful and easy to use programmable zipcode database in Python. It comes with a rich feature and easy-to-use zipcode search engine. And it is easy to customize the search behavior as you wish.

About the Data

Disclaimer

I started from a academic research project for personal use. I don't promise for data accuracy, please use with your own risk.

Where the data comes from?

The data is crawled from data.census.gov. There's data tool allows you to explore 1300+ data points of a zipcode. You can play it yourself with this link https://data.census.gov/cedsci/table?q=94103.

Is this data set Up-to-Date?

Even the data.census.gov use different source for different data fields. For example, the latest general population / income / education data by zipcode are still from Census2010. But population over time data are based from IRS until FY 2018.

In general, static statistic data are from Census 2010. Demographic statistics over time has data utill 2020.

How many Zipcode in this Database

There are 42,724 zipcodes in this database. There are four different type zipcode:

• STANDARD: most common zipcode
• PO Box: for post office
• UNIQUE: special location, usually a single building
• MILITARY: military location

Number of zipcodes for each type::

+--------------+-------+------------+
| zipcode_type | count | percentage |
+--------------+-------+------------+
|   STANDARD   | 30001 |   70.22    |
|    PO BOX    |  9397 |   21.99    |
|    UNIQUE    |  2539 |    5.94    |
|   MILITARY   |  787  |    1.84    |
+--------------+-------+------------+

I found a Great data source, how to contribute?

You can open an Issue <https://github.com/MacHu-GWU/uszipcode-project/issues/new?assignees=&labels=enhancement&template=i-found-a-data-source.md&title=I+found+a+data+source>_ and leave the URL of the data source, brief description about the dataset.

The Data point

Address, Postal

• zipcode
• zipcode_type
• major_city
• post_office_city
• common_city_list
• county
• state
• area_code_list

Geography

• lat
• lng
• timezone
• radius_in_miles
• land_area_in_sqmi
• water_area_in_sqmi
• bounds_west
• bounds_east
• bounds_north
• bounds_south
• border polygon

Stats and Demographics

• population
• population_density
• population_by_year
• population_by_age
• population_by_gender
• population_by_race
• head_of_household_by_age
• families_vs_singles
• households_with_kids
• children_by_age

Real Estate and Housing

• housing_units

• occupied_housing_units

• median_home_value

• median_household_income

• housing_type

• year_housing_was_built
• housing_occupancy
• vacancy_reason
• owner_occupied_home_values

• rental_properties_by_number_of_rooms

• monthly_rent_including_utilities_studio_apt

• monthly_rent_including_utilities_1_b
• monthly_rent_including_utilities_2_b
• monthly_rent_including_utilities_3plus_b

Employment, Income, Earnings, and Work

• employment_status
• average_household_income_over_time
• household_income

• annual_individual_earnings

• sources_of_household_income____percent_of_households_receiving_income

• sources_of_household_income____average_income_per_household_by_income_source

• household_investment_income____percent_of_households_receiving_investment_income

• household_investment_income____average_income_per_household_by_income_source

• household_retirement_income____percent_of_households_receiving_retirement_incom

• household_retirement_income____average_income_per_household_by_income_source

• source_of_earnings

• means_of_transportation_to_work_for_workers_16_and_over
• travel_time_to_work_in_minutes

Education

• educational_attainment_for_population_25_and_over
• school_enrollment_age_3_to_17

.. _install:

Install

uszipcode is released on PyPI, so all you need is:

.. code-block:: console

$ pip install uszipcode

To upgrade to latest version:

.. code-block:: console

$ pip install --upgrade uszipcode

Issues

Adding python-Levenshtein to silence warning

opened on 2023-02-26 19:07:00 by RGAlexander216

Silences a warning upon SearchEngine instantiation by having python-Levenshtein installed.

Update search.py

opened on 2023-02-26 18:57:34 by RGAlexander216

• Added the ability to specify the simple_or_comprehensive as an explicit string as well as a SearchEngine.SimpleOrComprehensiveEnum object
• Added type conversion for the lat, lng, and radius parameters in the SearchEngine class' query method with descriptive error handling

cannot import name 'SearchEngine' from 'uszipcode'

opened on 2023-01-09 20:00:53 by BolieRide

Describe the problem

cannot import name 'SearchEngine' from 'uszipcode' I am trying to use in a conda ArcGIS environment.

Sample code to reproduce the problem

from uszipcode import SearchEngine

package info

SQLAlchemy 1.4.46 sqlalchemy-mate 1.4.28.3 uszipcode 1.0.1

Thanks.

Fail to find a zipcode give a city and state

opened on 2022-10-26 19:25:14 by huangming6220

Describe the problem

Plymouth Minnesota Traceback (most recent call last): File "C:\Users\m184194\Documents\Mayo\Projects\Patten_Facebook\scripts\facebook-friends-map\test.py", line 14, in get_zipcode(current_city) File "C:\Users\m184194\Documents\Mayo\Projects\Patten_Facebook\scripts\facebook-friends-map\test.py", line 9, in get_zipcode zipcodes = engine.by_city_and_state(city=city, state=state) File "C:\Users\m184194\Anaconda3\envs\social_media\lib\site-packages\uszipcode\search.py", line 802, in by_city_and_state return self.query( File "C:\Users\m184194\Anaconda3\envs\social_media\lib\site-packages\uszipcode\search.py", line 536, in query city = self.find_city(city, state, best_match=True)[0] File "C:\Users\m184194\Anaconda3\envs\social_media\lib\site-packages\uszipcode\search.py", line 379, in find_city raise ValueError("'%s' is not a valid city name" % city) ValueError: 'Ely' is not a valid city name Exception ignored in: Traceback (most recent call last):

Sample code to reproduce the problem

from uszipcode import SearchEngine engine = SearchEngine()

def get_zipcode(current_city): city = current_city.split(",")[0].strip() state = current_city.split(",")[1].strip() print(city, state) zipcodes = engine.by_city_and_state(city=city, state=state) for zipcode in zipcodes: print(zipcode.zipcode, zipcode.major_city, zipcode.population)

current_city = "Plymouth, Minnesota" get_zipcode(current_city) engine.close()

Potential Solution

Maybe you can try talk to the author lively here https://gitter.im/MacHu-GWU-Python-Library-Technical-Support/community

Cannot operate on a closed database

opened on 2022-10-20 04:05:06 by mark-scherer

Python garbage collection triggers error within SearchEngine.__del__:

Exception ignored in: <function SearchEngine.__del__ at 0x1050100d0> Traceback (most recent call last): File "/usr/local/lib/python3.9/site-packages/uszipcode/search.py", line 196, in __del__ File "/usr/local/lib/python3.9/site-packages/uszipcode/search.py", line 202, in close File "/usr/local/lib/python3.9/site-packages/sqlalchemy/orm/session.py", line 1811, in close File "/usr/local/lib/python3.9/site-packages/sqlalchemy/orm/session.py", line 1853, in _close_impl File "/usr/local/lib/python3.9/site-packages/sqlalchemy/orm/session.py", line 923, in close File "/usr/local/lib/python3.9/site-packages/sqlalchemy/engine/base.py", line 2416, in close File "/usr/local/lib/python3.9/site-packages/sqlalchemy/engine/base.py", line 2639, in _do_close File "/usr/local/lib/python3.9/site-packages/sqlalchemy/engine/base.py", line 2625, in _close_impl File "/usr/local/lib/python3.9/site-packages/sqlalchemy/engine/base.py", line 2617, in _connection_rollback_impl File "/usr/local/lib/python3.9/site-packages/sqlalchemy/engine/base.py", line 1059, in _rollback_impl File "/usr/local/lib/python3.9/site-packages/sqlalchemy/engine/base.py", line 2124, in _handle_dbapi_exception File "/usr/local/lib/python3.9/site-packages/sqlalchemy/util/compat.py", line 208, in raise_ File "/usr/local/lib/python3.9/site-packages/sqlalchemy/engine/base.py", line 1057, in _rollback_impl File "/usr/local/lib/python3.9/site-packages/sqlalchemy/engine/default.py", line 683, in do_rollback sqlalchemy.exc.ProgrammingError: (sqlite3.ProgrammingError) Cannot operate on a closed database. (Background on this error at: https://sqlalche.me/e/14/f405)

Don't think this has to do with how I'm calling SearchEngine. Produces annoying error message when the script finishes.

How do you parse Common_city_list

opened on 2022-09-21 14:01:06 by 931743010

Want to use Data in simple_db.sqlite; Export to Excel; Common_city_list is displayed as eJyLVgouLSqqVIoFAA9dAyI= How do you parse this data; Python is not very good; How do you parse this data using Java?

Releases

1.0.1.db 2021-12-15 16:44:16

• comprehensive_db.sqlite
• simple_db.sqlite

0.2.6 db file 2021-04-21 01:29:46

• db.sqlite
• simple_db.sqlite

Version 0.1.3 2016-08-08 20:26:05

Version 0.1.2 2016-07-01 21:03:59

Version 0.1.1 2016-05-28 20:54:06

A first production release

Version 0.0.9 2016-02-24 23:15:00