countrystatecity-timezones

Official Python package for 432 IANA timezones with country associations, GMT offsets, and time conversion utilities. Part of the countrystatecity ecosystem.

From offline prototype to production

This package provides a versioned offline snapshot. For regularly updated data, server-side search and filtering, field-selected responses, or managed availability and support, use the Country State City API.

Get a free API key · API docs · Pricing · Migration guide

Keep API keys in server-side environment variables, never in client-side code or source control.

Installation

pip install countrystatecity-timezones

Quick Start

from countrystatecity_timezones import (
    get_all_timezones,
    get_timezones_by_country,
    get_timezone_by_zone_name,
    get_timezones_by_offset,
    search_timezones,
    convert_time,
)
from datetime import datetime

# Get all timezones
timezones = get_all_timezones()
# [Timezone(zoneName="Africa/Abidjan", gmtOffset=0, ...), ...]

# Get timezones for a country
us_timezones = get_timezones_by_country("US")
# [Timezone(zoneName="America/Adak", countryCode="US", ...), ...]

# Lookup by IANA zone name
tz = get_timezone_by_zone_name("America/New_York")
# Timezone(zoneName="America/New_York", gmtOffset=-18000, gmtOffsetName="UTC-05:00", ...)

# Filter by GMT offset (seconds)
utc_minus_5 = get_timezones_by_offset(-18000)

# Search by name or abbreviation
results = search_timezones("Eastern")

# Convert time between timezones
dt = datetime(2024, 1, 1, 12, 0, 0)
converted = convert_time(dt, "America/New_York", "Asia/Kolkata")
# datetime(2024, 1, 1, 22, 30, tzinfo=ZoneInfo("Asia/Kolkata"))

Data Model

class Timezone(BaseModel):
    zoneName: str        # IANA timezone name (e.g., "America/New_York")
    gmtOffset: int       # GMT offset in seconds (e.g., -18000)
    gmtOffsetName: str   # Human-readable offset (e.g., "UTC-05:00")
    abbreviation: str    # Timezone abbreviation (e.g., "EST")
    tzName: str          # Full timezone name (e.g., "Eastern Standard Time")
    countryCode: str     # ISO2 country code (e.g., "US")
    countryName: str     # Country name (e.g., "United States")

API Reference

License

ODbL-1.0 — see LICENSE.

Other Packages in this Ecosystem

Data sourced from countries-states-cities-database.

Made with ❤️ by dr5hn