Introduction
============
This package will allow you to get zip code information. The data used in this
package can be retrieved from
https://web.archive.org/web/20101126192032/http://pablotron.org/files/zipcodes-csv-10-Aug-2004.zip
`pyzipcode` uses a local sqlite database to run. You can replace it with your
own other storage mechanism with a little effort.
Here is some basic usage...
```pycon
>>> from pyzipcode import ZipCodeDatabase
>>> zcdb = ZipCodeDatabase()
>>> zcdb[54115]
ZipCode(zip='54115', city='De Pere', state='WI', longitude=-88.07896, latitude=44.42042, timezone=-6, dst=1)
>>> zcdb[210]
ZipCode(zip='00210', city='Portsmouth', state='NH', longitude=-71.013202, latitude=43.005895, timezone=-5, dst=1)
```
Search zip codes...
```pycon
>>> from pyzipcode import ZipCodeDatabase
>>> zcdb = ZipCodeDatabase()
>>> len(zcdb.find_zip(city="Oshkosh"))
7
>>> len(zcdb.find_zip(city="O%")) # all cities starting with "O" using SQL wildcard
60
>>> len(zcdb.find_zip(city="Doesn't Exist")) # returns None
>>>
```
Get a list of zipcodes around a radius of a zipcode (this actually searches a square area)
```pycon
>>> from pyzipcode import ZipCodeDatabase
>>> zcdb = ZipCodeDatabase()
>>> [z.zip for z in zcdb.get_zipcodes_around_radius('54901', 10)]
['54901', '54902', '54903', '54904', '54906', '54927', '54952', '54956', '54957', '54979', '54985']
```
The Data
========
The following is the original README file from `zipcodes-csv-10-Aug-2004.zip`:
```text
CivicSpace US ZIP Code Database
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
written by Schuyler Erle <schuyler@geocoder.us>
5 August 2004
corrected total count and removed sql table definition
Neil Drumm <neil@civicspacelabs.org>
10 August 2004
The ZIP code database contained in 'zipcode.csv' contains 43191 ZIP
codes for the continetal United States, Alaska, Hawaii, Puerto Rico,
and American Samoa. The database is in comma separated value format,
with columns for ZIP code, city, state, latitude, longitude, timezone
(offset from GMT), and daylight savings time flag (1 if DST is observed
in this ZIP code and 0 if not).
This database was composed using ZIP code gazetteers from the US Census
Bureau from 1999 and 2000, augmented with additional ZIP code information
from the Census Bureau's TIGER/Line 2003 data set. Timezone information
was added using cartographic data sets from nationalatlas.gov. The
database is guaranteed to exclusively contain information gathered from
sources in the public domain, and thus be legal to redistribute.
The database is believed to contain over 98% of the ZIP Codes in current
use in the United States. The remaining ZIP Codes absent from this
database are entirely PO Box or Firm ZIP codes added in the last five
years, which are no longer published by the Census Bureau, but in any
event serve a very small minority of the population (probably on the
order of .1% or less). Although every attempt has been made to filter
them out, this data set may contain up to .5% false positives, that is,
ZIP codes that do not exist or are no longer in use but are included due
to erroneous data sources. The latitude and longitude given for each ZIP
code is typically (though not always) the geographic centroid of the ZIP
code; in any event, the location given can generally be expected to lie
somewhere within the ZIP code's "boundaries".
The database andthis README are copyright 2004 CivicSpace Labs, Inc.,
and are published under a Creative Commons Attribution-ShareAlike
license, which requires that all updates must be released under the same
license. See http://creativecommons.org/licenses/by-sa/2.0/ for more
details. Please contact schuyler@geocoder.us if you are interested in
receiving updates to this database as they become available.
-=- 30 -=-
Visit http://civicspacelabs.org/zipcodedb for latest information.
```
# ChangeLog
3.0.1 (2021-03-03)
- Fix release
## 3.0.0 (2021-03-03)
- ZipCodeDatabase objects now behave like dictionaries
- Looking up a non-existent zipcode raises a KeyError instead of IndexError
- .get() now returns a ZipCode object instead of a list containing 1 ZipCode object
- they now have a len(), can be iterated over and reversed()
- they now have .keys() .values() and .items() methods
- ZipCode objects are created by passing multiple arguments, one for
each value, instead of a tuple
- Support looking up 4 and 3 digit zip codes as integers
- Drop Python 2 support
2.0.3 (unreleased)
---
- Nothing changed yet.
## 2.0.2 (2021-02-28)
- license update
## 2.0.1 (2021-02-25)
- Fix error message for unknown zip code[mpcusack]
## 2.0.0 (2020-04-07)
- updated to work with py3
[David Schneider]
1.0 (2016-01-20)
---
- Fix import code so that it is not run when the module is imported (for
example, when building Sphinx API Documentation).
- Rename the import.py module to import_zipcode.py because `import` is a
reserved Python keyword.
- Document the import_zipcode module.
0.4
---
- updated to use maxmind database http://www.maxmind.com/app/postalcode
- now also keeps timezone and dst values
- longitude and latitude is now contains negative numbers
## 0.3
- use strings instead of integer for storing zip codes since zip codes can start
with a Zero.
## 0.2
- catch sqlite db file reading errors and keep trying in case
another process is trying to access the file at the same time.
## 0.1
- initial release
Raw data
{
"_id": null,
"home_page": "https://github.com/vangheem/pyzipcode",
"name": "pyzipcode",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "zip code distance",
"author": "Nathan Van Gheem",
"author_email": "vangheem@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3f/b9/9cf79708df6bdcbbd512424cf5b7321b571b3477eb2e9648fec13e2b2b91/pyzipcode-3.0.1.tar.gz",
"platform": "",
"description": "Introduction\n============\n\nThis package will allow you to get zip code information. The data used in this\npackage can be retrieved from\nhttps://web.archive.org/web/20101126192032/http://pablotron.org/files/zipcodes-csv-10-Aug-2004.zip\n\n`pyzipcode` uses a local sqlite database to run. You can replace it with your\nown other storage mechanism with a little effort.\n\nHere is some basic usage...\n\n```pycon\n>>> from pyzipcode import ZipCodeDatabase\n>>> zcdb = ZipCodeDatabase()\n\n>>> zcdb[54115]\nZipCode(zip='54115', city='De Pere', state='WI', longitude=-88.07896, latitude=44.42042, timezone=-6, dst=1)\n>>> zcdb[210]\nZipCode(zip='00210', city='Portsmouth', state='NH', longitude=-71.013202, latitude=43.005895, timezone=-5, dst=1)\n```\n\nSearch zip codes...\n\n```pycon\n>>> from pyzipcode import ZipCodeDatabase\n>>> zcdb = ZipCodeDatabase()\n>>> len(zcdb.find_zip(city=\"Oshkosh\"))\n7\n>>> len(zcdb.find_zip(city=\"O%\")) # all cities starting with \"O\" using SQL wildcard\n60\n>>> len(zcdb.find_zip(city=\"Doesn't Exist\")) # returns None\n>>> \n```\n\nGet a list of zipcodes around a radius of a zipcode (this actually searches a square area)\n\n```pycon\n>>> from pyzipcode import ZipCodeDatabase\n>>> zcdb = ZipCodeDatabase()\n>>> [z.zip for z in zcdb.get_zipcodes_around_radius('54901', 10)]\n['54901', '54902', '54903', '54904', '54906', '54927', '54952', '54956', '54957', '54979', '54985']\n```\n\nThe Data\n========\n\nThe following is the original README file from `zipcodes-csv-10-Aug-2004.zip`:\n\n```text\nCivicSpace US ZIP Code Database\n-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-\nwritten by Schuyler Erle <schuyler@geocoder.us>\n5 August 2004\n\ncorrected total count and removed sql table definition\nNeil Drumm <neil@civicspacelabs.org>\n10 August 2004\n\nThe ZIP code database contained in 'zipcode.csv' contains 43191 ZIP\ncodes for the continetal United States, Alaska, Hawaii, Puerto Rico,\nand American Samoa. The database is in comma separated value format,\nwith columns for ZIP code, city, state, latitude, longitude, timezone\n(offset from GMT), and daylight savings time flag (1 if DST is observed\nin this ZIP code and 0 if not).\n\nThis database was composed using ZIP code gazetteers from the US Census\nBureau from 1999 and 2000, augmented with additional ZIP code information\nfrom the Census Bureau's TIGER/Line 2003 data set. Timezone information\nwas added using cartographic data sets from nationalatlas.gov. The\ndatabase is guaranteed to exclusively contain information gathered from\nsources in the public domain, and thus be legal to redistribute.\n\nThe database is believed to contain over 98% of the ZIP Codes in current\nuse in the United States. The remaining ZIP Codes absent from this\ndatabase are entirely PO Box or Firm ZIP codes added in the last five\nyears, which are no longer published by the Census Bureau, but in any\nevent serve a very small minority of the population (probably on the\norder of .1% or less). Although every attempt has been made to filter\nthem out, this data set may contain up to .5% false positives, that is,\nZIP codes that do not exist or are no longer in use but are included due\nto erroneous data sources. The latitude and longitude given for each ZIP\ncode is typically (though not always) the geographic centroid of the ZIP\ncode; in any event, the location given can generally be expected to lie\nsomewhere within the ZIP code's \"boundaries\".\n\nThe database andthis README are copyright 2004 CivicSpace Labs, Inc.,\nand are published under a Creative Commons Attribution-ShareAlike\nlicense, which requires that all updates must be released under the same\nlicense. See http://creativecommons.org/licenses/by-sa/2.0/ for more\ndetails. Please contact schuyler@geocoder.us if you are interested in\nreceiving updates to this database as they become available.\n\n-=- 30 -=-\n\nVisit http://civicspacelabs.org/zipcodedb for latest information.\n```\n\n\n\n# ChangeLog\n\n3.0.1 (2021-03-03)\n\n- Fix release\n\n## 3.0.0 (2021-03-03)\n\n- ZipCodeDatabase objects now behave like dictionaries\n - Looking up a non-existent zipcode raises a KeyError instead of IndexError\n - .get() now returns a ZipCode object instead of a list containing 1 ZipCode object\n - they now have a len(), can be iterated over and reversed()\n - they now have .keys() .values() and .items() methods\n- ZipCode objects are created by passing multiple arguments, one for\n each value, instead of a tuple\n- Support looking up 4 and 3 digit zip codes as integers\n- Drop Python 2 support\n\n 2.0.3 (unreleased)\n\n---\n\n- Nothing changed yet.\n\n## 2.0.2 (2021-02-28)\n\n- license update\n\n## 2.0.1 (2021-02-25)\n\n- Fix error message for unknown zip code[mpcusack]\n\n## 2.0.0 (2020-04-07)\n\n- updated to work with py3\n [David Schneider]\n\n 1.0 (2016-01-20)\n\n---\n\n- Fix import code so that it is not run when the module is imported (for\n example, when building Sphinx API Documentation).\n- Rename the import.py module to import_zipcode.py because `import` is a\n reserved Python keyword.\n- Document the import_zipcode module.\n\n 0.4\n\n---\n\n- updated to use maxmind database http://www.maxmind.com/app/postalcode\n\n- now also keeps timezone and dst values\n\n- longitude and latitude is now contains negative numbers\n\n## 0.3\n\n- use strings instead of integer for storing zip codes since zip codes can start\n with a Zero.\n\n## 0.2\n\n- catch sqlite db file reading errors and keep trying in case\n another process is trying to access the file at the same time.\n\n## 0.1\n\n- initial release",
"bugtrack_url": null,
"license": "MIT",
"summary": "query zip codes and location data",
"version": "3.0.1",
"project_urls": {
"Homepage": "https://github.com/vangheem/pyzipcode"
},
"split_keywords": [
"zip",
"code",
"distance"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3fb99cf79708df6bdcbbd512424cf5b7321b571b3477eb2e9648fec13e2b2b91",
"md5": "7f95a28b7652860ac975d5354d6dcfe9",
"sha256": "4146386c3f45dc9b5c30e537da60c7d58fac54d6312f24a718340f3c235cff1b"
},
"downloads": -1,
"filename": "pyzipcode-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "7f95a28b7652860ac975d5354d6dcfe9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 1934784,
"upload_time": "2021-03-03T17:01:47",
"upload_time_iso_8601": "2021-03-03T17:01:47.834109Z",
"url": "https://files.pythonhosted.org/packages/3f/b9/9cf79708df6bdcbbd512424cf5b7321b571b3477eb2e9648fec13e2b2b91/pyzipcode-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-03-03 17:01:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vangheem",
"github_project": "pyzipcode",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyzipcode"
}
JSON
