Skip to main content

Query U.S. state zipcodes without SQLite.

Project description

Zipcodes

Zipcodes is a simple library for querying over U.S. zipcode data.

The Python sqlite3 module is not required.

>>> import zipcodes
>>> assert zipcodes.is_real('77429')
>>> assert len(zipcodes.similar_to('7742')) != 0
>>> exact_zip = zipcodes.matching('77429')
>>> filtered_zip = zipcodes.filter_by({ 
        "city": "Cypress", 
        "state": "TX" 
    })
>>> assert exact_zip == filtered_zip
>>> pprint.pprint(exact_zip)
[{'acceptable_cities': [],
  'active': True,
  'area_codes': ['281', '832'],
  'city': 'Cypress',
  'country': 'US',
  'county': 'Harris County',
  'lat': '29.9857',
  'long': '-95.6548',
  'state': 'TX',
  'timezone': 'America/Chicago',
  'unacceptable_cities': [],
  'world_region': 'NA',
  'zip_code': '77429',
  'zip_code_type': 'STANDARD'}]

⚠️ The zipcode data was last updated on: Nov. 13th, 2019 ⚠️

Downloads Supported Versions Contributors

Installation

Zipcodes is available on PyPI:

$ python -m pip install zipcodes

Requests supports Python 2.6+ & 3.2+.

Compiling with PyInstaller

Add a data file to your PyInstaller bundle with the --add-data flag.

Linux and MacOS

--add-data "<path-to-package-install>/zipcodes/zips.json.bz2:zipcodes"

Windows

--add-data "<path-to-package-install>\zipcodes\zips.json.bz2;zipcodes"

Zipcode Data

The build script for the zipcode data outputs a JSON file containing all the zipcode data and zipped using bzip2. The data sources are stored under build/app/data.

Build the zipcode data for distribution:

$ build/app/__init__.py # outputs `zipcodes/zips.json.bz2`

Tests

The tests are defined in a declarative, table-based format that generates test cases.

Run the tests directly:

$ python tests/__init__.py 

Examples

>>> from pprint import pprint
>>> import zipcodes

>>> # Simple zip-code matching.
>>> pprint(zipcodes.matching('77429'))
[{'acceptable_cities': [],
  'active': True,
  'area_codes': ['281', '832'],
  'city': 'Cypress',
  'country': 'US',
  'county': 'Harris County',
  'lat': '29.9857',
  'long': '-95.6548',
  'state': 'TX',
  'timezone': 'America/Chicago',
  'unacceptable_cities': [],
  'world_region': 'NA',
  'zip_code': '77429',
  'zip_code_type': 'STANDARD'}]


>>> # Handles of Zip+4 zip-codes nicely. :)
>>> pprint(zipcodes.matching('77429-1145'))
[{'acceptable_cities': [],
  'active': True,
  'area_codes': ['281', '832'],
  'city': 'Cypress',
  'country': 'US',
  'county': 'Harris County',
  'lat': '29.9857',
  'long': '-95.6548',
  'state': 'TX',
  'timezone': 'America/Chicago',
  'unacceptable_cities': [],
  'world_region': 'NA',
  'zip_code': '77429',
  'zip_code_type': 'STANDARD'}]

>>> # Will try to handle invalid zip-codes gracefully...
>>> print(zipcodes.matching('06463'))
[]

>>> # Until it cannot.
>>> zipcodes.matching('0646a')
Traceback (most recent call last):
  ...
TypeError: Invalid characters, zipcode may only contain digits and "-".

>>> zipcodes.matching('064690')
Traceback (most recent call last):
  ...
TypeError: Invalid format, zipcode must be of the format: "#####" or "#####-####"

>>> zipcodes.matching(None)
Traceback (most recent call last):
  ...
TypeError: Invalid type, zipcode must be a string.

>>> # Whether the zip-code exists within the database.
>>> print(zipcodes.is_real('06463'))
False

>>> # How handy!
>>> print(zipcodes.is_real('06469'))
True

>>> # Search for zipcodes that begin with a pattern.
>>> pprint(zipcodes.similar_to('1018'))
[{'acceptable_cities': [],
  'active': False,
  'area_codes': ['212'],
  'city': 'New York',
  'country': 'US',
  'county': 'New York County',
  'lat': '40.71',
  'long': '-74',
  'state': 'NY',
  'timezone': 'America/New_York',
  'unacceptable_cities': ['J C Penney'],
  'world_region': 'NA',
  'zip_code': '10184',
  'zip_code_type': 'UNIQUE'},
 {'acceptable_cities': [],
  'active': True,
  'area_codes': ['212'],
  'city': 'New York',
  'country': 'US',
  'county': 'New York County',
  'lat': '40.7143',
  'long': '-74.0067',
  'state': 'NY',
  'timezone': 'America/New_York',
  'unacceptable_cities': [],
  'world_region': 'NA',
  'zip_code': '10185',
  'zip_code_type': 'PO BOX'}]

>>> # Use filter_by to filter a list of zip-codes by specific attribute->value pairs.
>>> pprint(zipcodes.filter_by(city="Old Saybrook"))
[{'acceptable_cities': [],
  'active': True,
  'area_codes': ['860'],
  'city': 'Old Saybrook',
  'country': 'US',
  'county': 'Middlesex County',
  'lat': '41.3015',
  'long': '-72.3879',
  'state': 'CT',
  'timezone': 'America/New_York',
  'unacceptable_cities': ['Fenwick'],
  'world_region': 'NA',
  'zip_code': '06475',
  'zip_code_type': 'STANDARD'}]

>>> # Arbitrary nesting of similar_to and filter_by calls, allowing for great precision while filtering.
>>> pprint(zipcodes.similar_to('2', zips=zipcodes.filter_by(active=True, city='Windsor')))
[{'acceptable_cities': [],
  'active': True,
  'area_codes': ['757'],
  'city': 'Windsor',
  'country': 'US',
  'county': 'Isle of Wight County',
  'lat': '36.8628',
  'long': '-76.7143',
  'state': 'VA',
  'timezone': 'America/New_York',
  'unacceptable_cities': [],
  'world_region': 'NA',
  'zip_code': '23487',
  'zip_code_type': 'STANDARD'},
 {'acceptable_cities': ['Askewville'],
  'active': True,
  'area_codes': ['252'],
  'city': 'Windsor',
  'country': 'US',
  'county': 'Bertie County',
  'lat': '35.9942',
  'long': '-76.9422',
  'state': 'NC',
  'timezone': 'America/New_York',
  'unacceptable_cities': [],
  'world_region': 'NA',
  'zip_code': '27983',
  'zip_code_type': 'STANDARD'},
 {'acceptable_cities': [],
  'active': True,
  'area_codes': ['803'],
  'city': 'Windsor',
  'country': 'US',
  'county': 'Aiken County',
  'lat': '33.4730',
  'long': '-81.5132',
  'state': 'SC',
  'timezone': 'America/New_York',
  'unacceptable_cities': [],
  'world_region': 'NA',
  'zip_code': '29856',
  'zip_code_type': 'STANDARD'}]

>>> # Have any other ideas? Make a pull request and start contributing today!
>>> # Made with love by Sean Pianka

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for zipcodes, version 1.1.3
Filename, size File type Python version Upload date Hashes
Filename, size zipcodes-1.1.3-py2.py3-none-any.whl (720.3 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size zipcodes-1.1.3.tar.gz (722.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page