Skip to main content

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.

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)

Source distribution for zip2tz 0.1.7
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)

Table of built distributions (wheels) for zip2tz 0.1.7
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page