Lightweight U.S. zip-code validation package for Python (2 and 3).
Project description
Zipcodes
A lightweight U.S. zip-code validation package for Python (2 and 3). This package was built as zipcode provided too much functionality and relied on sqlite3, which is not available on platforms such as AWS Lambda. While more difficult to add additional zip-codes, this package provides the essential functionality of zip-code validation with fewer dependencies and minimal working logic.
Contributions are welcome!
Installation
$ pip install zipcodes
Synopsis
Below is the expected usage of this package and a demonstration of supported functionality.
>>> from pprint import pprint
>>> import zipcodes
>>> # Simple zip-code matching.
>>> pprint(zipcodes.matching('77429'))
[{'zip_code': '77429',
'zip_code_type': 'STANDARD',
'city': 'CYPRESS',
'state': 'TX',
'lat': 29.96,
'long': -95.69,
'world_region': 'NA',
'country': 'US',
'active': True}]
>>> # Handles of Zip+4 zip-codes nicely. :)
>>> pprint(zipcodes.matching('77429-1145'))
[{'zip_code': '77429',
'zip_code_type': 'STANDARD',
'city': 'CYPRESS',
'state': 'TX',
'lat': 29.96,
'long': -95.69,
'world_region': 'NA',
'country': 'US',
'active': True}]
>>> # Will try to handle invalid zip-codes gracefully...
>>> print(zipcodes.matching('06463'))
[]
>>> # Until it cannot.
>>> zipcodes.matching('abc123')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/sean/Development/Zipcodes/zipcodes/__init__.py", line 30, in <lambda>
return lambda zipcode, *args, **kwargs: f(_validate(zipcode), *args, **kwargs)
File "/home/sean/Development/Zipcodes/zipcodes/__init__.py", line 181, in _validate
'state': 'SC',
TypeError: Zipcode may only contain digits and "-".
>>> # Whether the zip-code exists within the database.
>>> print(zipcodes.is_valid('06463'))
False
>>> # How handy!
>>> print(zipcodes.is_valid('06469'))
True
>>> # Search for zipcodes that begin with a pattern.
>>> pprint(zipcodes.similar_to('0643'))
[{'active': True,
'city': 'GUILFORD',
'country': 'US',
'lat': 41.28,
'long': -72.67,
'state': 'CT',
'world_region': 'NA',
'zip_code': '06437',
'zip_code_type': 'STANDARD'},
{'active': True,
'city': 'HADDAM',
'country': 'US',
'lat': 41.45,
'long': -72.5,
'state': 'CT',
'world_region': 'NA',
'zip_code': '06438',
'zip_code_type': 'STANDARD'},
... # remaining results truncated for readability...
]
>>> # Use filter_by to filter a list of zip-codes by specific attribute->value pairs.
>>> pprint(zipcodes.filter_by(zipcodes.list_all(), active=True, city='WINDSOR'))
[{'active': True,
'city': 'WINDSOR',
'country': 'US',
'lat': 44.31,
'long': -69.58,
'state': 'ME',
'world_region': 'NA',
'zip_code': '04363',
'zip_code_type': 'STANDARD'},
{'active': True,
'city': 'WINDSOR',
'country': 'US',
'lat': 43.48,
'long': -72.42,
'state': 'VT',
'world_region': 'NA',
'zip_code': '05089',
'zip_code_type': 'STANDARD'},
... # remaining results truncated for readability...
]
>>> # Arbitrary nesting of similar_to and filter_by calls, allowing for great precision while filtering.
>>> pprint(zipcodes.similar_to('2', zips=zipcodes.filter_by(zipcodes.list_all(), active=True, city='WINDSOR')))
[{'active': True,
'city': 'WINDSOR',
'country': 'US',
'lat': 33.48,
'long': -81.51,
'state': 'SC',
'world_region': 'NA',
'zip_code': '29856',
'zip_code_type': 'STANDARD'},
{'active': True,
'city': 'WINDSOR',
'country': 'US',
'lat': 36.8,
'long': -76.73,
'state': 'VA',
'world_region': 'NA',
'zip_code': '23487',
'zip_code_type': 'STANDARD'},
{'active': True,
'city': 'WINDSOR',
'country': 'US',
'lat': 36.0,
'long': -76.94,
'state': 'NC',
'world_region': 'NA',
'zip_code': '27983',
'zip_code_type': 'STANDARD'}]
>>> # Have any other ideas? Make a pull request and start contributing today!
>>> # Made with love by Sean Pianka
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
zipcodes-1.0.4.tar.gz
(572.6 kB
view hashes)
Built Distribution
zipcodes-1.0.4-py2.py3-none-any.whl
(573.1 kB
view hashes)
Close
Hashes for zipcodes-1.0.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1db2fd46f6ed7fed772c05165e49510cd9e7df8f018f326c2c7f1c496d20584c |
|
MD5 | 42e0bf113af491b597fc9fe5ba99a0bb |
|
BLAKE2b-256 | 5c69ab0666e57ed40d5b93182308e23fb3a3417a69ee3ac4869b810c44423a79 |