Usage Example¶
Get Zipcode Statistics and Demographic Data¶
from uszipcode import SearchEngine
sr = SearchEngine()
z = sr.by_zipcode("10001")
print(z)
z = sr.by_zipcode(10001)
print(z)
Simple vs Comprehensive Zipcode Database¶
uszipcode
has two backend database, SimpleZipcode
and ComprehensiveZipcode
. ComprehensiveZipcode
has more data points, but the database file is 450MB (takes more time to download). SimpleZipcode
doesn’t has all data points listed above, but the database file is smaller (10MB). By default uszipcode
use SimpleZipcode
. You can use this code to choose to use the rich info Zipcode
:
>>> from uszipcode import SearchEngine
# use simple zipcode
>>> search = SearchEngine(
... simple_or_comprehensive=SearchEngine.SimpleOrComprehensiveArgEnum.simple
)
# use comprehensive zipcode
>>> search = SearchEngine(
... simple_or_comprehensive=SearchEngine.SimpleOrComprehensiveArgEnum.comprehensive
)
Change the Default Database File location¶
uszipcode
allows developer to choose which directory you want to use to download the database file**. By default, it is $HOME/.uszipcode
, but you can easily change it.:
>>> search = SearchEngine(db_file_path="/tmp/simple_db.sqlite")
For example, AWS Lambda doesn’t allow to download file to $HOME directory, but allows to download to /tmp
folder.
Change the Default Download URL¶
By default, the database file are hosted on GitHub. But you can host it elsewhere like your private storage.
>>> search = SearchEngine(download_url="https://your-private-storage.sqlite")
SearchEngine Examples¶
>>> from uszipcode import SearchEngine
>>> search = SearchEngine(simple_zipcode=True) # set simple_zipcode=False to use rich info database
>>> zipcode = search.by_zipcode("10001")
>>> zipcode
SimpleZipcode(zipcode=u'10001', zipcode_type=u'Standard', major_city=u'New York', post_office_city=u'New York, NY', common_city_list=[u'New York'], county=u'New York County', state=u'NY', lat=40.75, lng=-73.99, timezone=u'Eastern', radius_in_miles=0.9090909090909091, area_code_list=[u'718', u'917', u'347', u'646'], population=21102, population_density=33959.0, land_area_in_sqmi=0.62, water_area_in_sqmi=0.0, housing_units=12476, occupied_housing_units=11031, median_home_value=650200, median_household_income=81671, bounds_west=-74.008621, bounds_east=-73.984076, bounds_north=40.759731, bounds_south=40.743451)
>>> zipcode.values() # to list
[u'10001', u'Standard', u'New York', u'New York, NY', [u'New York'], u'New York County', u'NY', 40.75, -73.99, u'Eastern', 0.9090909090909091, [u'718', u'917', u'347', u'646'], 21102, 33959.0, 0.62, 0.0, 12476, 11031, 650200, 81671, -74.008621, -73.984076, 40.759731, 40.743451]
>>> zipcode.to_dict() # to dict
{'housing_units': 12476, 'post_office_city': u'New York, NY', 'bounds_east': -73.984076, 'county': u'New York County', 'population_density': 33959.0, 'radius_in_miles': 0.9090909090909091, 'timezone': u'Eastern', 'lng': -73.99, 'common_city_list': [u'New York'], 'zipcode_type': u'Standard', 'zipcode': u'10001', 'state': u'NY', 'major_city': u'New York', 'population': 21102, 'bounds_west': -74.008621, 'land_area_in_sqmi': 0.62, 'lat': 40.75, 'median_household_income': 81671, 'occupied_housing_units': 11031, 'bounds_north': 40.759731, 'bounds_south': 40.743451, 'area_code_list': [u'718', u'917', u'347', u'646'], 'median_home_value': 650200, 'water_area_in_sqmi': 0.0}
>>> zipcode.to_json() # to json
{
"zipcode": "10001",
"zipcode_type": "Standard",
"major_city": "New York",
"post_office_city": "New York, NY",
"common_city_list": [
"New York"
],
"county": "New York County",
"state": "NY",
"lat": 40.75,
"lng": -73.99,
"timezone": "Eastern",
"radius_in_miles": 0.9090909090909091,
"area_code_list": [
"718",
"917",
"347",
"646"
],
"population": 21102,
"population_density": 33959.0,
"land_area_in_sqmi": 0.62,
"water_area_in_sqmi": 0.0,
"housing_units": 12476,
"occupied_housing_units": 11031,
"median_home_value": 650200,
"median_household_income": 81671,
"bounds_west": -74.008621,
"bounds_east": -73.984076,
"bounds_north": 40.759731,
"bounds_south": 40.743451
}
Rich search methods are provided for getting zipcode in the way you want.
>>> from uszipcode import Zipcode
# Search zipcode within 30 miles, ordered from closest to farthest
>>> result = search.by_coordinates(39.122229, -77.133578, radius=30, returns=5)
>>> len(res) # by default 5 results returned
5
>>> for zipcode in result:
... # do whatever you want...
# Find top 10 population zipcode
>>> result = search.by_population(lower=0, upper=999999999,
... sort_by=Zipcode.population, ascending=False, returns=10)
# Find top 10 largest land area zipcode
>>> res = search.by_landarea(lower=0, upper=999999999,
... sort_by=Zipcode.land_area_in_sqmi, ascending=False, returns=10)
Zipcode Type¶
By default, most of zipcode query only returns STANDARD zipcode. If you want all zipcode or specific type of zipcode, you can do:
>>> from uszipcode import ZipcodeTypeEnum
# return all zipcode type
>>> res = sr.by_coordinates(..., zipcode_type=None)
# return only PO box type
>>> res = sr.by_coordinates(..., zipcode_type=ZipcodeTypeEnum.PO_Box)
Fuzzy city name and state name search does not require developer to know the exact spelling of the city or state. And it is case, space insensitive, having high tolerance to typo. This is very helpful if you need to build a web app with it.
# Looking for Chicago and IL, but entered wrong spelling.
>>> res = search.by_city_and_state("cicago", "il", returns=999) # only returns first 999 results
>>> len(res) # 56 zipcodes in Chicago
56
>>> zipcode = res[0]
>>> zipcode.major_city
'Chicago'
>>> zipcode.state_abbr
'IL'
You can easily sort your results by any field, or distance from a coordinates if you query by location.
# Find top 10 population zipcode
>>> res = search.by_population(lower=0, upper=999999999,
... sort_by=Zipcode.population, ascending=False, returns=10)
>>> for zipcode in res:
... # do whatever you want...
Deploy uszipcode as a Web Service¶
I collect lots of feedback from organization user that people want to host the database file privately. And people may love to use different rdbms backend like mysql or psql. From 0.2.6
, this is easy.
Host the database file privately
download db file from https://github.com/MacHu-GWU/uszipcode-project/releases/download/1.0.1.db/simple_db.sqlite
upload it to your private storage.
use
download_url
parameter:
search = SearchEngine(download_url="https://your-private-store.sqlite")
Use different RDBMS backend:
Let’s use MySQL as example.
Download db file.
use DBeaver to connect to both sqlite and mysql.
dump sqlite as csv and load it to mysql.
use
engine
parameter
import sqlalchemy_mate as sam
engine = sam.EngineCreator(username, password, host, port, database)..create_postgresql_pg8000()
search = SearchEngine(engine=engine)
Deploy uszipcode as Web API:
Use a VM like EC2 machine, and deploy a web api server with the machine.
(RECOMMEND) Dump the sqlite database to any relational database like Postgres, MySQL, and inject the database connection info in your application server.