zip2tz 0.1.2

A simple timezone lookup by zip code

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 None if 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:

1. Fork the repository
2. Make your changes
3. Open a pull request

For data corrections, please include a reliable source for the timezone mapping.

License

MIT License — see LICENSE for details.