{"id":19725019,"url":"https://github.com/seanpianka/zipcodes","last_synced_at":"2025-05-16T11:04:55.780Z","repository":{"id":44646447,"uuid":"98949932","full_name":"seanpianka/Zipcodes","owner":"seanpianka","description":"A simple library for querying U.S. zipcodes.","archived":false,"fork":false,"pushed_at":"2025-02-16T06:20:20.000Z","size":5794,"stargazers_count":79,"open_issues_count":2,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-13T21:16:41.006Z","etag":null,"topics":["aws-lambda","codes","postal","python","python2","python3","sqlite","zipcode","zipcodes"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seanpianka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-01T02:22:42.000Z","updated_at":"2025-03-20T14:43:26.000Z","dependencies_parsed_at":"2024-06-18T18:20:32.827Z","dependency_job_id":"81ca6e54-1be3-4770-847b-b0f74d5672b9","html_url":"https://github.com/seanpianka/Zipcodes","commit_stats":{"total_commits":51,"total_committers":6,"mean_commits":8.5,"dds":0.1568627450980392,"last_synced_commit":"e063248d3c9d79a57cc29117a235ba7eed4d43aa"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanpianka%2FZipcodes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanpianka%2FZipcodes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanpianka%2FZipcodes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanpianka%2FZipcodes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seanpianka","download_url":"https://codeload.github.com/seanpianka/Zipcodes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254518384,"owners_count":22084374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-lambda","codes","postal","python","python2","python3","sqlite","zipcode","zipcodes"],"created_at":"2024-11-11T23:27:52.652Z","updated_at":"2025-05-16T11:04:50.772Z","avatar_url":"https://github.com/seanpianka.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zipcodes\n\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/zipcodes)\n[![Downloads](https://static.pepy.tech/badge/zipcodes/month)](https://pepy.tech/project/zipcodes)\n[![Contributors](https://img.shields.io/github/contributors/seanpianka/zipcodes.svg)](https://github.com/seanpianka/zipcodes/graphs/contributors)\n\nZipcodes is a simple library for querying U.S. zipcodes.\n\nThe Python `sqlite3` module is not required in order to use this package.\n\n```python\n\u003e\u003e\u003e import zipcodes\n\u003e\u003e\u003e assert zipcodes.is_real('77429')\n\u003e\u003e\u003e assert len(zipcodes.similar_to('7742')) != 0\n\u003e\u003e\u003e exact_zip = zipcodes.matching('77429')[0]\n\u003e\u003e\u003e filtered_zips = zipcodes.filter_by(city=\"Cypress\", state=\"TX\") \n\u003e\u003e\u003e assert exact_zip in filtered_zips\n\u003e\u003e\u003e pprint.pprint(exact_zip)\n{'acceptable_cities': [],\n  'active': True,\n  'area_codes': ['281', '832'],\n  'city': 'Cypress',\n  'country': 'US',\n  'county': 'Harris County',\n  'lat': '29.9857',\n  'long': '-95.6548',\n  'state': 'TX',\n  'timezone': 'America/Chicago',\n  'unacceptable_cities': [],\n  'world_region': 'NA',\n  'zip_code': '77429',\n  'zip_code_type': 'STANDARD'}[\n```\n\n⚠️ The zipcode data was last updated on: **Feb. 16, 2025** ⚠️\n\n## Installation\n\nZipcodes is available on PyPI:\n\n```console\n$ python -m pip install zipcodes\n```\n\nZipcodes supports Python 2.6+ and Python 3.2+.\n\n### Compiling with PyInstaller\n\nAdd a data file to your PyInstaller bundle with the [`--add-data`](https://pyinstaller.readthedocs.io/en/stable/spec-files.html#adding-data-files) flag.\n\n\n#### Linux and MacOS\n`--add-data \"\u003cpath-to-package-install\u003e/zipcodes/zips.json.bz2:zipcodes\"`\n\n#### Windows\n`--add-data \"\u003cpath-to-package-install\u003e\\zipcodes\\zips.json.bz2;zipcodes\"`\n\n## Zipcode Data\n\nThe 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`. \n\nBuild the zipcode data for distribution: \n\n```shell script\n$ build/app/__init__.py # outputs `zipcodes/zips.json.bz2`\n```\n\n\n## Tests\n\nThe tests are defined in a declarative, table-based format that generates test\ncases. \n\nRun the tests directly:\n\n```shell script\n$ python tests/__init__.py \n```\n\n## Examples\n\n```python\n\u003e\u003e\u003e from pprint import pprint\n\u003e\u003e\u003e import zipcodes\n\n\u003e\u003e\u003e # Simple zip-code matching.\n\u003e\u003e\u003e pprint(zipcodes.matching('77429'))\n[{'acceptable_cities': [],\n  'active': True,\n  'area_codes': ['281', '832'],\n  'city': 'Cypress',\n  'country': 'US',\n  'county': 'Harris County',\n  'lat': '29.9857',\n  'long': '-95.6548',\n  'state': 'TX',\n  'timezone': 'America/Chicago',\n  'unacceptable_cities': [],\n  'world_region': 'NA',\n  'zip_code': '77429',\n  'zip_code_type': 'STANDARD'}]\n\n\n\u003e\u003e\u003e # Handles of Zip+4 zip-codes nicely. :)\n\u003e\u003e\u003e pprint(zipcodes.matching('77429-1145'))\n[{'acceptable_cities': [],\n  'active': True,\n  'area_codes': ['281', '832'],\n  'city': 'Cypress',\n  'country': 'US',\n  'county': 'Harris County',\n  'lat': '29.9857',\n  'long': '-95.6548',\n  'state': 'TX',\n  'timezone': 'America/Chicago',\n  'unacceptable_cities': [],\n  'world_region': 'NA',\n  'zip_code': '77429',\n  'zip_code_type': 'STANDARD'}]\n\n\u003e\u003e\u003e # Will try to handle invalid zip-codes gracefully...\n\u003e\u003e\u003e print(zipcodes.matching('06463'))\n[]\n\n\u003e\u003e\u003e # Until it cannot.\n\u003e\u003e\u003e zipcodes.matching('0646a')\nTraceback (most recent call last):\n  ...\nValueError: Invalid characters, zipcode may only contain digits and \"-\".\n\n\u003e\u003e\u003e zipcodes.matching('064690')\nTraceback (most recent call last):\n  ...\nValueError: Invalid format, zipcode must be of the format: \"#####\" or \"#####-####\"\n\n\u003e\u003e\u003e zipcodes.matching(None)\nTraceback (most recent call last):\n  ...\nTypeError: Invalid type, zipcode must be a string.\n\n\u003e\u003e\u003e # Whether the zip-code exists within the database.\n\u003e\u003e\u003e print(zipcodes.is_real('06463'))\nFalse\n\n\u003e\u003e\u003e # How handy!\n\u003e\u003e\u003e print(zipcodes.is_real('06469'))\nTrue\n\n\u003e\u003e\u003e # Search for zipcodes that begin with a pattern.\n\u003e\u003e\u003e pprint(zipcodes.similar_to('1018'))\n[{'acceptable_cities': [],\n  'active': False,\n  'area_codes': ['212'],\n  'city': 'New York',\n  'country': 'US',\n  'county': 'New York County',\n  'lat': '40.71',\n  'long': '-74',\n  'state': 'NY',\n  'timezone': 'America/New_York',\n  'unacceptable_cities': ['J C Penney'],\n  'world_region': 'NA',\n  'zip_code': '10184',\n  'zip_code_type': 'UNIQUE'},\n {'acceptable_cities': [],\n  'active': True,\n  'area_codes': ['212'],\n  'city': 'New York',\n  'country': 'US',\n  'county': 'New York County',\n  'lat': '40.7143',\n  'long': '-74.0067',\n  'state': 'NY',\n  'timezone': 'America/New_York',\n  'unacceptable_cities': [],\n  'world_region': 'NA',\n  'zip_code': '10185',\n  'zip_code_type': 'PO BOX'}]\n\n\u003e\u003e\u003e # Use filter_by to filter a list of zip-codes by specific attribute-\u003evalue pairs.\n\u003e\u003e\u003e pprint(zipcodes.filter_by(city=\"Old Saybrook\"))\n[{'acceptable_cities': [],\n  'active': True,\n  'area_codes': ['860'],\n  'city': 'Old Saybrook',\n  'country': 'US',\n  'county': 'Middlesex County',\n  'lat': '41.3015',\n  'long': '-72.3879',\n  'state': 'CT',\n  'timezone': 'America/New_York',\n  'unacceptable_cities': ['Fenwick'],\n  'world_region': 'NA',\n  'zip_code': '06475',\n  'zip_code_type': 'STANDARD'}]\n\n\u003e\u003e\u003e # Arbitrary nesting of similar_to and filter_by calls, allowing for great precision while filtering.\n\u003e\u003e\u003e pprint(zipcodes.similar_to('2', zips=zipcodes.filter_by(active=True, city='Windsor')))\n[{'acceptable_cities': [],\n  'active': True,\n  'area_codes': ['757'],\n  'city': 'Windsor',\n  'country': 'US',\n  'county': 'Isle of Wight County',\n  'lat': '36.8628',\n  'long': '-76.7143',\n  'state': 'VA',\n  'timezone': 'America/New_York',\n  'unacceptable_cities': [],\n  'world_region': 'NA',\n  'zip_code': '23487',\n  'zip_code_type': 'STANDARD'},\n {'acceptable_cities': ['Askewville'],\n  'active': True,\n  'area_codes': ['252'],\n  'city': 'Windsor',\n  'country': 'US',\n  'county': 'Bertie County',\n  'lat': '35.9942',\n  'long': '-76.9422',\n  'state': 'NC',\n  'timezone': 'America/New_York',\n  'unacceptable_cities': [],\n  'world_region': 'NA',\n  'zip_code': '27983',\n  'zip_code_type': 'STANDARD'},\n {'acceptable_cities': [],\n  'active': True,\n  'area_codes': ['803'],\n  'city': 'Windsor',\n  'country': 'US',\n  'county': 'Aiken County',\n  'lat': '33.4730',\n  'long': '-81.5132',\n  'state': 'SC',\n  'timezone': 'America/New_York',\n  'unacceptable_cities': [],\n  'world_region': 'NA',\n  'zip_code': '29856',\n  'zip_code_type': 'STANDARD'}]\n\n\u003e\u003e\u003e # Have any other ideas? Make a pull request and start contributing today!\n\u003e\u003e\u003e # Made with love by Sean Pianka\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseanpianka%2Fzipcodes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseanpianka%2Fzipcodes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseanpianka%2Fzipcodes/lists"}