Metadata-Version: 2.4
Name: ziptotimezone
Version: 1.0.0
Summary: Convert US zip codes to time zones
Author-email: Tim Lambert <tim@lakeshoreky.com>
License: MIT
Project-URL: Homepage, https://github.com/LakeshoreTim/ZipToTimezone-python
Project-URL: Repository, https://github.com/LakeshoreTim/ZipToTimezone-python
Keywords: zip code,zipcode,time zone,timezone,standard time,daylight savings time
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ZipToTimezone Python SDK

[![Python Version](https://img.shields.io/badge/python-%3E%3D3.8-3776AB.svg)](https://python.org/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Python SDK for ZipToTimezone — convert US zip codes to time zones. This is
a Python port of the [ZipToTimezone-php] library (also available as the
[ZipToTimezone-node] library), ported and verified against it for every
recognized zip code (00000–99999).

## Requirements

- Python 3.8 or higher

## Installation

```bash
pip install ziptotimezone
```

## Usage

```python
from ziptotimezone import calc_timezone_name, get_standard_time_offset, get_dst_offset

# Get the time zone name from a given zip code
input_zip = "60606"
output = calc_timezone_name(input_zip)
print(f"The time zone for {input_zip} is {output}")
# The time zone for 60606 is America/Chicago

# Get the time zone offset from UTC from a given zip code (Standard Time)
input_zip = "90210"
output = get_standard_time_offset(input_zip)
print(f"The Standard Time offset for {input_zip} is {output}")
# The Standard Time offset for 90210 is -8

# Get the time zone offset from UTC from a given zip code (Daylight Saving Time)
input_zip = "86023"
output = get_dst_offset(input_zip)
print(f"The Daylight Saving Time offset for {input_zip} is {output}")
# The Daylight Saving Time offset for 86023 is -7
```

Zip codes may be passed as an `int` or a `str`. ZIP+4 codes are accepted;
only the first 5 digits are used. Unrecognized zip codes return
`"unknown"` from `calc_timezone_name` and `0` from the offset functions.

## API

### `calc_timezone_name(zip_code)`

Returns the IANA timezone name (e.g. `"America/Chicago"`) for a zip code,
or `"unknown"` if it isn't recognized.

### `get_standard_time_offset(zip_code)`

Returns the Standard Time UTC offset, in whole hours, for a zip code (e.g.
`-5` for `America/New_York`), or `0` if it isn't recognized.

### `get_dst_offset(zip_code)`

Returns the Daylight Saving Time UTC offset, in whole hours, for a zip code
(e.g. `-4` for `America/New_York`), or `0` if it isn't recognized. Zones
that don't observe DST (Arizona, Hawaii) return their Standard Time offset
unchanged.

## Testing

```bash
python -m unittest discover -s tests
```

## Staying in Sync with IANA Time Zone Data

Time zone rules aren't static — Daylight Saving Time observance and UTC
offsets occasionally change at the government level. This library's data
is checked against [IANA's tzdata](https://github.com/eggert/tz) (the
canonical time zone database used by most operating systems and
programming languages) via an automated process that watches for new
releases mentioning any of the 25 zones this library covers, so that a
real-world rule change doesn't go unnoticed.

## License

MIT License - see [LICENSE](LICENSE) file.

## Links

- [GitHub Repository](https://github.com/LakeshoreTim/ZipToTimezone-python)
- [PHP version](https://github.com/LakeshoreTim/ZipToTimezone-php)
- [Node.js version](https://github.com/LakeshoreTim/ZipToTimezone-node)

[ZipToTimezone-php]: https://github.com/LakeshoreTim/ZipToTimezone-php
[ZipToTimezone-node]: https://github.com/LakeshoreTim/ZipToTimezone-node
