Timezones

Time zones are the core of the API. List and filter them, or fetch a single zone by its IANA identifier for full live detail.

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.

Query parameters

Parameter Type Description
country string ISO 3166-1 alpha-2 country code. Case-insensitive (fr, US).
observes_dst boolean true/false (also 1/0). Keep only zones that do or don't observe DST.
q string Search across the IANA identifier and display name. Max 100 characters.
sort string iana, display_name, or offset. Prefix with - for descending (e.g. -offset). Default iana.
offset string Filter by standard UTC offset. Accepts -04:00 or bare minutes like -240.
abbreviation string Filter by abbreviation/code such as EST or CET. Case-insensitive, max 10 characters.
is_mainland boolean true/false. Keep only mainland (or outlying) zones.
detail string concise (default) or full. full returns the detail shape per row.
per_page integer Results per page, 1–500. Default 50.
page integer Page number, 1 or greater. Default 1.

Example

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

{
  "data": [
    {
      "iana": "Europe/Amsterdam",
      "display_name": "Amsterdam",
      "country": { "code": "NL", "name": "Netherlands" },
      "current": {
        "utc_offset": "+02:00",
        "abbreviation": "CEST",
        "is_dst": true
      },
      "observes_dst": true,
      "links": {
        "self": "https://api.timezone.io/v1/timezones/Europe/Amsterdam"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 40,
    "tzdb_version": "2026a",
    "generated_at": "2026-05-31T12:00:00+00:00"
  },
  "links": {
    "first": "https://api.timezone.io/v1/timezones?abbreviation=cet&sort=display_name&page=1",
    "last": "https://api.timezone.io/v1/timezones?abbreviation=cet&sort=display_name&page=1",
    "prev": null,
    "next": null
  }
}

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. For Etc/GMT+N zones, percent-encode the + as %2B — e.g. Etc/GMT%2B5.

Query parameters

Parameter Type Description
at string Compute the time-dependent fields at a specific moment instead of now. Accepts an ISO-8601 datetime (2026-01-15T12:00:00Z) or a Unix timestamp (1768478400).

Response

The response is grouped into blocks:

Block Description
current Live local time, offset, abbreviation, friendly name, and DST flag.
standard The zone's standard (non-DST) offset, abbreviation, and name.
dst DST savings and the next_transition (or null if none in the next 5 years).
coordinates Latitude and longitude (either may be null).
links Related API URLs plus web, the human-readable page on timezone.io. 
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.7128, "longitude": -74.006 },
    "country": { "code": "US", "name": "United States" },
    "current": {
      "datetime": "2026-05-31T08:00:00-04:00",
      "utc_datetime": "2026-05-31T12: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": "2026a",
    "generated_at": "2026-05-31T12:00:00+00:00"
  }
}

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

The abbreviation and country links resolve to live Abbreviations and Countries endpoints.