zip2tz
Fast, zero-dependency US zip code to timezone lookup for Python.
- 38,000+ zip codes mapped to IANA timezones
- Zero dependencies — pure Python, works everywhere
- O(1) lookup — instant hash table lookups, no database or file I/O
- Tiny footprint — ~100KB installed, loads in milliseconds
- Type-annotated — full type hints included
Installation
pip install zip2tz
Or with uv:
uv add zip2tz
Usage
import zip2tz
# Get timezone for a zip code
tz = zip2tz.timezone("90210")
print(tz) # America/Los_Angeles
tz = zip2tz.timezone("10001")
print(tz) # America/New_York
# Works with integers too
tz = zip2tz.timezone(60601)
print(tz) # America/Chicago
# Returns None if zip code not found
tz = zip2tz.timezone("00000")
print(tz) # None
Why zip2tz?
Most timezone lookup libraries require external databases, network calls, or heavy dependencies. zip2tz bakes the data directly into Python bytecode — just import and go.
| Feature | zip2tz | Other libraries |
|---|---|---|
| Dependencies | 0 | Often requires pytz, databases, or APIs |
| Lookup speed | O(1) hash | Varies (file I/O, network, etc.) |
| Install size | ~100KB | Often MB+ |
| Offline | Yes | Sometimes requires network |
API
timezone(zipcode: str | int) -> str | None
Returns the IANA timezone string (e.g., "America/New_York") for the given US zip code, or None if not found.
Parameters:
zipcode— A 5-digit US zip code as a string or integer
Returns:
- IANA timezone string, or
Noneif the zip code is not in the database
Coverage
Covers all 50 US states plus DC, including:
- All continental US timezones
- Alaska (9 timezones)
- Hawaii
- Indiana's complex county-level timezone boundaries
- North Dakota's split counties
Data Accuracy
This library provides timezone mappings on a best-effort basis. While we strive for accuracy, we make no guarantees that the data is complete or correct. Timezone boundaries can be complex (especially in states like Indiana and Arizona), and zip codes occasionally span multiple timezones.
If you find an incorrect mapping or missing zip code, please open an issue with:
- The zip code in question
- The expected timezone
- A source for the correct mapping (if available)
Contributing
Contributions are welcome! If you'd like to improve the data or code:
- Fork the repository
- Make your changes
- Open a pull request
For data corrections, please include a reliable source for the timezone mapping.
License
MIT License — see LICENSE for details.
Metadata
Release files for zip2tz 0.1.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zip2tz-0.1.7.tar.gz | 111.6 kB | Without provenance | Details for zip2tz-0.1.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zip2tz-0.1.7-py3-none-any.whl | Python 3 | none | any | Details for zip2tz-0.1.7-py3-none-any.whl |
Total release size: 214.8 kB
Release files / zip2tz-0.1.7.tar.gz
| Download URL | zip2tz-0.1.7.tar.gz |
|---|---|
| Size | 111.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
defc0a579e425c6251d2f41379b1ec5c494ed71b0b1ddfbe11f1a10dcff9cea0
|
|
BLAKE2b-256 checksum How to use checksums |
0372ec861716bf38e3215a0fc62641cf23f35cb0b3dee783ef5d68097f499c14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / zip2tz-0.1.7-py3-none-any.whl
| Download URL | zip2tz-0.1.7-py3-none-any.whl |
|---|---|
| Size | 103.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ea75ebc9572a7ee879c31d0a702ae92b1ef23d96c583e6749dd654448df6963
|
|
BLAKE2b-256 checksum How to use checksums |
ba340fcb5fabef0ce3b1e4295af4bedb848564d818b064338aa248bbffdd5c34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for zip2tz 0.1.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.