Timezones

Time zones are the core of the API: every IANA zone with live offsets, DST state, and upcoming transitions.

At a glance#

List time zones#

GET /v1/timezones

Returns a paginated list of time zones. By default each row is concise — enough to render a list or populate a picker.

Example — power a timezone picker#

Your user picked United States in a settings form; show them their country's zones in a friendly order:

curl "https://api.timezone.io/v1/timezones?country=us&sort=display_name" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
    "data": [
        {
            "iana": "America/Adak",
            "display_name": "Adak",
            "country": { "code": "US", "name": "United States" },
            "current": {
                "utc_offset": "-09:00",
                "abbreviation": "HDT",
                "is_dst": true
            },
            "observes_dst": true,
            "links": {
                "self": "https://api.timezone.io/v1/timezones/America/Adak"
            }
        },
        {
            "iana": "America/Anchorage",
            "display_name": "Anchorage",
            "country": { "code": "US", "name": "United States" },
            "current": {
                "utc_offset": "-08:00",
                "abbreviation": "AKDT",
                "is_dst": true
            },
            "observes_dst": true,
            "links": {
                "self": "https://api.timezone.io/v1/timezones/America/Anchorage"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 50,
        "total": 29,
        "tzdb_version": "2025.2",
        "generated_at": "2026-06-12T09:00:00+00:00"
    },
    "links": {
        "first": "https://api.timezone.io/v1/timezones?country=us&sort=display_name&page=1",
        "last": "https://api.timezone.io/v1/timezones?country=us&sort=display_name&page=1",
        "prev": null,
        "next": null
    }
}

(Remaining 27 rows trimmed.) Show users the display_name and keep the iana value for your database — nobody picks "America/Indiana/Indianapolis" off a menu.

Query parameters#

Going deeper#

• offset filters on the standard offset, not the current one — a zone observing DST right now still matches its winter offset. To find zones currently at a given offset, filter by abbreviation instead, or use detail=full and read current.
• detail=full trades payload size for round trips. One request for a country's zones with full DST detail beats N follow-up lookups — see rate limits.
• Combine filters freely; they AND together (?country=us&observes_dst=false is the set of US zones that never change their clocks).

Retrieve a time zone#

GET /v1/timezones/{iana}

Fetch a single zone by its IANA identifier (for example America/New_York). The slash in the identifier is part of the path.

Example — warn users about an upcoming clock change#

A scheduling app wants to flag that a recurring 9 am New York meeting will shift for European invitees when the US falls back. dst.next_transition says exactly when and by how much:

curl https://api.timezone.io/v1/timezones/America/New_York \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
    "data": {
        "iana": "America/New_York",
        "display_name": "New York",
        "observes_dst": true,
        "is_mainland": true,
        "coordinates": { "latitude": 40.71416, "longitude": -74.00638 },
        "country": { "code": "US", "name": "United States" },
        "current": {
            "datetime": "2026-06-12T05:00:00-04:00",
            "utc_datetime": "2026-06-12T09:00:00Z",
            "utc_offset": "-04:00",
            "utc_offset_seconds": -14400,
            "abbreviation": "EDT",
            "name": "Eastern Daylight Time",
            "is_dst": true
        },
        "standard": {
            "utc_offset": "-05:00",
            "utc_offset_seconds": -18000,
            "abbreviation": "EST",
            "name": "Eastern Standard Time"
        },
        "dst": {
            "savings_seconds": 3600,
            "next_transition": {
                "type": "fall_back",
                "at": "2026-11-01T06:00:00Z",
                "utc_offset_after": "-05:00",
                "abbreviation_after": "EST",
                "clock_change_seconds": -3600
            }
        },
        "links": {
            "self": "https://api.timezone.io/v1/timezones/America/New_York",
            "country": "https://api.timezone.io/v1/countries/US",
            "abbreviation": "https://api.timezone.io/v1/abbreviations/EDT",
            "web": "https://timezone.io/iana/America/New_York"
        }
    },
    "meta": {
        "tzdb_version": "2025.2",
        "generated_at": "2026-06-12T09:00:00+00:00"
    }
}

Reading it: on November 1, 2026 at 06:00 UTC the zone falls back (clock_change_seconds is -3600), after which it is EST at -05:00. Your 9 am New York meeting lands an hour later for everyone whose zone doesn't change that week.

Query parameters#

Response fields#

The response is grouped into blocks:

Going deeper#

• Percent-encode +. For Etc/GMT+N zones, encode the + as %2B — e.g. Etc/GMT%2B5. A literal + in a URL decodes as a space and returns 404.
• at answers historical and future questions. ?at=2026-01-15T12:00:00Z tells you what offset New York had in January; the dst.next_transition is computed relative to that moment too.
• A zone with observes_dst: false still has a dst block — savings_seconds is 0 and next_transition is null, so your parsing code never branches.
• The abbreviation and country links resolve to live Abbreviations and Countries endpoints.

A missing identifier returns 404. See Errors for the full list of responses.