Skip to main content

zip2info

Fast, zero-dependency US ZIP code lookups for Python.

  • 41,000+ zip codes mapped to IANA timezones, including Puerto Rico and the territories
  • Geocoordinates for ZIP centroids (latitude/longitude)
  • Zero dependencies — pure Python, works everywhere
  • O(1) lookup — instant hash table lookups, no database or file I/O
  • Type-annotated — full type hints included

Installation

pip install zip2info

Or with uv:

uv add zip2info

Usage

import zip2info

# Timezone lookup
tz = zip2info.timezone("90210")
print(tz)  # America/Los_Angeles

# Coordinate lookup (latitude, longitude)
coords = zip2info.coordinates("90210")
print(coords)  # (34.0901, -118.4065)

# Rich metadata
record = zip2info.info("10001")
print(record.timezone)   # America/New_York
print(record.latitude)   # 40.7484
print(record.longitude)  # -73.9967

# Works with integers too
tz = zip2info.timezone(60601)
print(tz)  # America/Chicago

# Returns None if zip code not found
tz = zip2info.timezone("00000")
print(tz)  # None

API

timezone(zipcode: str | int) -> str | None

Returns the IANA timezone string for a US ZIP code.

coordinates(zipcode: str | int) -> tuple[float, float] | None

Returns (latitude, longitude) for a US ZIP code, or None if unavailable.

info(zipcode: str | int) -> ZipInfo | None

Returns a ZipInfo dataclass with zipcode, timezone, latitude, and longitude. Returns None when timezone or coordinate data is unavailable.

Data sources

  • Coordinates (merged in priority order):
    1. U.S. Census ZCTA gazetteer centroids (public domain)
    2. GeoNames postal codes for the US and its territories (CC BY 4.0)
    3. Manual overrides in data/coordinate_overrides.json
  • Timezones: derived from each ZIP centroid at build time with timezonefinder. Deriving rather than copying is what lets coverage track the upstream feeds; the shipped package stays dependency-free.

Only US timezones are shipped. A ZIP centroid can land on foreign soil — APO/FPO/DPO codes carry the coordinates of the overseas base — and those ZIPs are omitted rather than reported with a foreign local time. Note that America/ is a continent, not a country, so it is not a usable filter on its own.

Regenerate packaged data with:

python scripts/compile_data.py

Migration from zip2tz

zip2info is a new PyPI package and import path. Existing zip2tz installs are unchanged.

# before
import zip2tz
zip2tz.timezone("90210")

# after
import zip2info
zip2info.timezone("90210")

Coverage

Covers all 50 US states plus DC, including Alaska, Hawaii, Indiana county-level boundaries, and other edge cases.

Data accuracy

Timezone and coordinate mappings are provided on a best-effort basis. ZIP codes can span multiple timezones or areas, and coordinate points are centroids/estimates rather than exact address locations.

If you find incorrect data, please open an issue with the ZIP code, expected value, and a source if available.

License

MIT License — see LICENSE for details.

Coordinate data includes GeoNames material licensed under CC BY 4.0.

Metadata

Release files for zip2info 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zip2info 1.1.0
File Size Uploaded Provenance Actions
zip2info-1.1.0.tar.gz 411.3 kB Without provenance Details for zip2info-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zip2info 1.1.0
File Interpreter ABI Platform Actions
zip2info-1.1.0-py3-none-any.whl Python 3 none any Details for zip2info-1.1.0-py3-none-any.whl

Total release size: 781.0 kB

Release files / zip2info-1.1.0.tar.gz

Download URL zip2info-1.1.0.tar.gz
Size 411.3 kB
Tags Source
SHA-256 checksum
How to use checksums
bd5e11308cbeab754e2fa51782124225e7efad3e1001be39bfa5855deb6675c9
BLAKE2b-256 checksum
How to use checksums
3f346c606f4a3ab923c335d41c9230e2e72573ef811b994cb31328b81f9d401e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.12 {"installer":{"name":"uv","version":"0.12.12","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 / zip2info-1.1.0-py3-none-any.whl

Download URL zip2info-1.1.0-py3-none-any.whl
Size 369.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f600fe3b491b3eca614340c6b062c97110dbdd8af63e55ff4459993139eb81c3
BLAKE2b-256 checksum
How to use checksums
27f6c0de9fb90cbb94be502af1cb34d2da7dc701bad4845b4918ba297286d6f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.12 {"installer":{"name":"uv","version":"0.12.12","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 zip2info 1.1.0

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