Metadata-Version: 2.1
Name: zipcode-coordinates-tz
Version: 0.1.3
Summary: A Python package for querying US Zipcodes, and converting to coordinates and timezones
License: Apache
Keywords: geolocation,zipcodes,census,timezone,timezone-converter,postal-codes,pytz,usps
Author: Robert Colfin
Author-email: robert.m.colfin@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
Requires-Dist: aiohttp (>=3.11.10,<4.0.0)
Requires-Dist: asyncclick (>=8.1.7.2,<9.0.0.0)
Requires-Dist: backoff (>=2.2.1,<3.0.0)
Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pytz (>=2024.2,<2025.0)
Requires-Dist: timezonefinder (>=6.5.7,<7.0.0)
Requires-Dist: xlrd (>=2.0.1,<3.0.0)
Project-URL: homepage, https://github.com/rcolfin/zipcode-coordinates-tz
Description-Content-Type: text/markdown

# zipcode-coordinates-tz

[![CI Build](https://github.com/rcolfin/zipcode-coordinates-tz/actions/workflows/ci.yml/badge.svg)](https://github.com/rcolfin/zipcode-coordinates-tz/actions/workflows/ci.yml)
[![PyPI Version](https://img.shields.io/pypi/v/zipcode-coordinates-tz)](https://pypi.python.org/pypi/zipcode-coordinates-tz)
[![versions](https://img.shields.io/pypi/pyversions/zipcode-coordinates-tz.svg)](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.

