Metadata-Version: 2.1
Name: zipcode-coordinates-tz
Version: 0.5.0
Summary: A Python package for querying US Zipcodes, and converting to coordinates and timezones
Keywords: geolocation,zipcodes,census,timezone,timezone-converter,postal-codes,pytz,usps
Author-Email: Robert Colfin <robert.m.colfin@gmail.com>
License: Apache
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Project-URL: homepage, https://github.com/rcolfin/zipcode-coordinates-tz
Requires-Python: <4.0,>=3.9
Requires-Dist: aiofiles<26.0.0,>=25.1.0
Requires-Dist: asyncclick<9.0.0.0,>=8.1.7.2
Requires-Dist: curl-cffi>=0.13.0
Requires-Dist: openpyxl<4.0.0,>=3.1.5
Requires-Dist: pytz<2027.0,>=2024.2
Requires-Dist: timezonefinder<9.0.0,>=6.5.7
Requires-Dist: xlrd<3.0.0,>=2.0.1
Requires-Dist: pandas>=1
Requires-Dist: tenacity>=9.1.2
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)
[![License](https://img.shields.io/github/license/rcolfin/zipcode-coordinates-tz.svg)](https://github.com/rcolfin/zipcode-coordinates-tz/blob/main/LICENSE)
[![PyPI Version](https://img.shields.io/pypi/v/zipcode-coordinates-tz)](https://pypi.org/project/zipcode-coordinates-tz/)
[![versions](https://img.shields.io/pypi/pyversions/zipcode-coordinates-tz.svg)](https://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)

The first time run

```sh
uvx pre-commit install
```

### If you need to relock:

Run [scripts/lock.sh](scripts/lock.sh)

### Run code

Run [scripts/console.sh](scripts/console.sh) uv run jupyter notebook


## API Usage:

```zipcode-coordinates-tz
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.
