# zipcode-coordinates-tz
[](https://github.com/rcolfin/zipcode-coordinates-tz/actions/workflows/ci.yml)
[](https://pypi.python.org/pypi/zipcode-coordinates-tz)
[](ttps://github.com/rcolfin/zipcode-coordinates-tz)
A Python package that enables converting a US Zip Code into a timezone. This is done through the querying of the USPS API, then joining it with the zipcode-coordinates-tz data from the US Census, and finally taking the coordinates and using `timezonefinder` to determine the timezone.
## Dependencies:
- [Geocoding Services Web Application Programming Interface (API)](https://geocoding.geo.census.gov/geocoder/Geocoding_Services_API.pdf)
- [ZIP Codes by Area and District codes](https://postalpro.usps.com/ZIP_Locale_Detail)
- [timezonefinder](https://timezonefinder.readthedocs.io/en/stable/)
## Development
### Setup Python Environment:
Run [scripts/console.sh](../scripts/console.sh) poetry install
### If you need to relock:
Run [scripts/lock.sh](../scripts/lock.sh)
### Run code
Run [scripts/console.sh](../scripts/console.sh) poetry run jupyter notebook
## API Usage:
```python
from zipcode_coordinates_tz import census, postal, timezone
df_postal_locales = await postal.get_locales()
df_postal_locales = df_postal_locales.loc[df_postal_locales.State == "NJ"]
df_postal_locales = await census.get_coordinates(df_postal_locales)
df_postal_locales = timezone.fill_timezones(df_postal_locales, fill_missing=True)
print(df_postal_locales)
```
As a CLI
```sh
python -m zipcode_coordinates_tz save NJ.json --state NJ --timezones --fill
```
## Installation
To install zipcode-coordinates-tz from PyPI, use the following command:
$ pip install zipcode-coordinates-tz
You can also clone the repo and run the following command in the project root to install the source code as editable:
$ pip install -e .
## Documentation
The documentation for `zipcode-coordinates-tz` can be found [here](https://rcolfin.github.io/zipcode-coordinates-tz/) or in the project's docstrings.
Raw data
{
"_id": null,
"home_page": null,
"name": "zipcode-coordinates-tz",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "geolocation, zipcodes, census, timezone, timezone-converter, postal-codes, pytz, usps",
"author": "Robert Colfin",
"author_email": "robert.m.colfin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/00/a4/3549f1deb1fb4cacc326481f8e6aaa584b523a5fad2de7ff7905994dbe18/zipcode_coordinates_tz-0.2.0.tar.gz",
"platform": null,
"description": "# zipcode-coordinates-tz\n\n[](https://github.com/rcolfin/zipcode-coordinates-tz/actions/workflows/ci.yml)\n[](https://pypi.python.org/pypi/zipcode-coordinates-tz)\n[](ttps://github.com/rcolfin/zipcode-coordinates-tz)\n\nA Python package that enables converting a US Zip Code into a timezone. This is done through the querying of the USPS API, then joining it with the zipcode-coordinates-tz data from the US Census, and finally taking the coordinates and using `timezonefinder` to determine the timezone.\n\n## Dependencies:\n- [Geocoding Services Web Application Programming Interface (API)](https://geocoding.geo.census.gov/geocoder/Geocoding_Services_API.pdf)\n- [ZIP Codes by Area and District codes](https://postalpro.usps.com/ZIP_Locale_Detail)\n- [timezonefinder](https://timezonefinder.readthedocs.io/en/stable/)\n\n## Development\n\n### Setup Python Environment:\n\nRun [scripts/console.sh](../scripts/console.sh) poetry install\n\n### If you need to relock:\n\nRun [scripts/lock.sh](../scripts/lock.sh)\n\n### Run code\n\nRun [scripts/console.sh](../scripts/console.sh) poetry run jupyter notebook\n\n\n## API Usage:\n\n```python\nfrom zipcode_coordinates_tz import census, postal, timezone\n\ndf_postal_locales = await postal.get_locales()\ndf_postal_locales = df_postal_locales.loc[df_postal_locales.State == \"NJ\"]\ndf_postal_locales = await census.get_coordinates(df_postal_locales)\ndf_postal_locales = timezone.fill_timezones(df_postal_locales, fill_missing=True)\nprint(df_postal_locales)\n```\n\nAs a CLI\n\n```sh\npython -m zipcode_coordinates_tz save NJ.json --state NJ --timezones --fill\n```\n\n## Installation\n\nTo install zipcode-coordinates-tz from PyPI, use the following command:\n\n $ pip install zipcode-coordinates-tz\n\nYou can also clone the repo and run the following command in the project root to install the source code as editable:\n\n $ pip install -e .\n\n## Documentation\nThe documentation for `zipcode-coordinates-tz` can be found [here](https://rcolfin.github.io/zipcode-coordinates-tz/) or in the project's docstrings.\n",
"bugtrack_url": null,
"license": "Apache",
"summary": "A Python package for querying US Zipcodes, and converting to coordinates and timezones",
"version": "0.2.0",
"project_urls": {
"homepage": "https://github.com/rcolfin/zipcode-coordinates-tz"
},
"split_keywords": [
"geolocation",
" zipcodes",
" census",
" timezone",
" timezone-converter",
" postal-codes",
" pytz",
" usps"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ccfc7843aa981aa6154831d4c49026a0e9c6d1040ba466a168dcd98c91277391",
"md5": "558dde7264ce88c40ece970fed1ecb11",
"sha256": "6c8c9391c9d3287e7d516fa5e5e1b740bfb1449fa3ddebc4c2dde2dba924dc60"
},
"downloads": -1,
"filename": "zipcode_coordinates_tz-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "558dde7264ce88c40ece970fed1ecb11",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 17159,
"upload_time": "2024-12-19T13:27:53",
"upload_time_iso_8601": "2024-12-19T13:27:53.802789Z",
"url": "https://files.pythonhosted.org/packages/cc/fc/7843aa981aa6154831d4c49026a0e9c6d1040ba466a168dcd98c91277391/zipcode_coordinates_tz-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "00a43549f1deb1fb4cacc326481f8e6aaa584b523a5fad2de7ff7905994dbe18",
"md5": "426b6a3bd93fa7a5a47c5ff88a72220b",
"sha256": "e3a754ef9417759e618ed6c675fa9ca22913198498a52fd29b45e81ce038e5c7"
},
"downloads": -1,
"filename": "zipcode_coordinates_tz-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "426b6a3bd93fa7a5a47c5ff88a72220b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 14588,
"upload_time": "2024-12-19T13:27:54",
"upload_time_iso_8601": "2024-12-19T13:27:54.782826Z",
"url": "https://files.pythonhosted.org/packages/00/a4/3549f1deb1fb4cacc326481f8e6aaa584b523a5fad2de7ff7905994dbe18/zipcode_coordinates_tz-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-19 13:27:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rcolfin",
"github_project": "zipcode-coordinates-tz",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zipcode-coordinates-tz"
}