7 releases
0.3.4 | Mar 29, 2024 |
---|---|
0.3.3 | Feb 23, 2023 |
0.3.2 | Dec 21, 2022 |
0.3.1 | Sep 26, 2022 |
0.1.0 | Sep 26, 2022 |
#442 in Text processing
406 downloads per month
715KB
102 lines
Zipcodes
Zipcodes is a simple library for querying U.S. zipcodes.
No system installation of sqlite3
is not required in order to use this package, which is ideal for cloud environments like AWS Lambda.
use zipcodes;
fn main() {
zipcodes::is_real("77429")
}
// >>> import zipcodes
// >>> assert zipcodes.is_real('77429')
// >>> assert len(zipcodes.similar_to('7742')) // != 0
// >>> exact_zip = zipcodes.matching('77429')[0]
// >>> filtered_zips = zipcodes.filter_by// (city="Cypress", state="TX")
// >>> assert exact_zip in filtered_zips
// >>> 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: Oct. 3, 2021 ⚠️
Installation
Zipcodes is available on crates.io:
$ cargo add zipcodes
or add the following to your Cargo.toml
:
[dependencies]
zipcodes = "0.3"
Zipcodes has no explicit MSRV.
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`
Examples
TODO: Migrate from Python.
>>> 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):
...
ValueError: Invalid characters, zipcode may only contain digits and "-".
>>> zipcodes.matching('064690')
Traceback (most recent call last):
...
ValueError: 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
Dependencies
~1.4–2.6MB
~49K SLoC