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.
```rust use zipcodes;
fn main() { zipcodes::is_real("77429") }
// >>> import zipcodes // >>> assert zipcodes.isreal('77429') // >>> assert len(zipcodes.similarto('7742')) // != 0 // >>> exactzip = zipcodes.matching('77429')[0] // >>> filteredzips = zipcodes.filterby// (city="Cypress", state="TX") // >>> assert exactzip in filteredzips // >>> pprint.pprint(exactzip) // {'acceptablecities': [], // 'active': True, // 'areacodes': ['281', '832'], // 'city': 'Cypress', // 'country': 'US', // 'county': 'Harris County', // 'lat': '29.9857', // 'long': '-95.6548', // 'state': 'TX', // 'timezone': 'America/Chicago', // 'unacceptablecities': [], // 'worldregion': 'NA', // 'zipcode': '77429', // 'zipcode_type': 'STANDARD'}[ ```
⚠️ The zipcode data was last updated on: Oct. 3, 2021 ⚠️
Zipcodes is available on crates.io:
console
$ cargo add zipcodes
or add the following to your Cargo.toml:
toml
[dependencies]
zipcodes = "0.3"
Zipcodes has no explicit MSRV.
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:
shell script
$ build/app/__init__.py # outputs `zipcodes/zips.json.bz2`
TODO: Migrate from Python.
```python
from pprint import pprint import zipcodes
Simple zip-code matching.
pprint(zipcodes.matching('77429')) [{'acceptablecities': [], 'active': True, 'areacodes': ['281', '832'], 'city': 'Cypress', 'country': 'US', 'county': 'Harris County', 'lat': '29.9857', 'long': '-95.6548', 'state': 'TX', 'timezone': 'America/Chicago', 'unacceptablecities': [], 'worldregion': 'NA', 'zipcode': '77429', 'zipcode_type': 'STANDARD'}]
Handles of Zip+4 zip-codes nicely. :)
pprint(zipcodes.matching('77429-1145')) [{'acceptablecities': [], 'active': True, 'areacodes': ['281', '832'], 'city': 'Cypress', 'country': 'US', 'county': 'Harris County', 'lat': '29.9857', 'long': '-95.6548', 'state': 'TX', 'timezone': 'America/Chicago', 'unacceptablecities': [], 'worldregion': 'NA', 'zipcode': '77429', 'zipcode_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.similarto('1018')) [{'acceptablecities': [], 'active': False, 'areacodes': ['212'], 'city': 'New York', 'country': 'US', 'county': 'New York County', 'lat': '40.71', 'long': '-74', 'state': 'NY', 'timezone': 'America/NewYork', 'unacceptablecities': ['J C Penney'], 'worldregion': 'NA', 'zipcode': '10184', 'zipcodetype': 'UNIQUE'}, {'acceptablecities': [], 'active': True, 'areacodes': ['212'], 'city': 'New York', 'country': 'US', 'county': 'New York County', 'lat': '40.7143', 'long': '-74.0067', 'state': 'NY', 'timezone': 'America/NewYork', 'unacceptablecities': [], 'worldregion': 'NA', 'zipcode': '10185', 'zipcode_type': 'PO BOX'}]
Use filter_by to filter a list of zip-codes by specific attribute->value pairs.
pprint(zipcodes.filterby(city="Old Saybrook")) [{'acceptablecities': [], 'active': True, 'areacodes': ['860'], 'city': 'Old Saybrook', 'country': 'US', 'county': 'Middlesex County', 'lat': '41.3015', 'long': '-72.3879', 'state': 'CT', 'timezone': 'America/NewYork', 'unacceptablecities': ['Fenwick'], 'worldregion': 'NA', 'zipcode': '06475', 'zipcode_type': 'STANDARD'}]
Arbitrary nesting of similarto and filterby calls, allowing for great precision while filtering.
pprint(zipcodes.similarto('2', zips=zipcodes.filterby(active=True, city='Windsor'))) [{'acceptablecities': [], 'active': True, 'areacodes': ['757'], 'city': 'Windsor', 'country': 'US', 'county': 'Isle of Wight County', 'lat': '36.8628', 'long': '-76.7143', 'state': 'VA', 'timezone': 'America/NewYork', 'unacceptablecities': [], 'worldregion': 'NA', 'zipcode': '23487', 'zipcodetype': 'STANDARD'}, {'acceptablecities': ['Askewville'], 'active': True, 'areacodes': ['252'], 'city': 'Windsor', 'country': 'US', 'county': 'Bertie County', 'lat': '35.9942', 'long': '-76.9422', 'state': 'NC', 'timezone': 'America/NewYork', 'unacceptablecities': [], 'worldregion': 'NA', 'zipcode': '27983', 'zipcodetype': 'STANDARD'}, {'acceptablecities': [], 'active': True, 'areacodes': ['803'], 'city': 'Windsor', 'country': 'US', 'county': 'Aiken County', 'lat': '33.4730', 'long': '-81.5132', 'state': 'SC', 'timezone': 'America/NewYork', 'unacceptablecities': [], 'worldregion': 'NA', 'zipcode': '29856', 'zipcodetype': 'STANDARD'}]
Have any other ideas? Make a pull request and start contributing today!
Made with love by Sean Pianka
```