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": "2026d",
        "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/eastern-daylight-time",
            "web": "https://timezone.io/iana/America/New_York"
        }
    },
    "meta": {
        "tzdb_version": "2026d",
        "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, so your parsing code never branches: savings_seconds is 0, and next_transition is null unless one last switch is still ahead, such as a new abbreviation at the same offset.
• The abbreviation and country links resolve to live Abbreviations and Countries endpoints. The abbreviation link uses the named zone's slug, never its code, because codes collide (AST names several zones) and a bare code can answer 300.

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