Timezone API

A clean, dependable JSON API for the world's time zones. Every IANA time zone comes with live UTC offsets, daylight-saving status, upcoming transitions, and the countries that use them — all computed in real time from the IANA time zone database.

The API is currently in v1. Today it covers time zones, abbreviations, countries, and cities; time conversion is coming next.

Base URL

All endpoints live under a single versioned base URL:

https://api.timezone.io/v1

Every request must be authenticated and is served over HTTPS as JSON. See Authentication to get a key, then jump to the Timezones, Abbreviations, Countries, and Cities endpoints.

A first request

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

{
  "data": [
    {
      "iana": "Europe/Paris",
      "display_name": "Paris",
      "country": { "code": "FR", "name": "France" },
      "current": {
        "utc_offset": "+02:00",
        "abbreviation": "CEST",
        "is_dst": true
      },
      "observes_dst": true,
      "links": {
        "self": "https://api.timezone.io/v1/timezones/Europe/Paris"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 1,
    "tzdb_version": "2026a",
    "generated_at": "2026-05-31T12:00:00+00:00"
  },
  "links": { "first": "…", "last": "…", "prev": null, "next": null }
}

Response format

Successful responses follow Laravel's resource envelope:

Key Description
data The resource, or an array of resources for list endpoints.
meta Metadata — pagination for lists, plus tzdb_version and generated_at.
links Related URLs. On lists, the pagination links (first, last, prev, next).

Conventions

  • JSON only. Every response — including errors — is JSON. You do not need to send an Accept header.
  • snake_case keys throughout.
  • Datetimes are ISO-8601. Local times carry their offset (2026-05-31T08:00:00-04:00); UTC instants use Zulu notation (2026-05-31T12:00:00Z).
  • Offsets are given both as a string (-04:00) and as integer seconds (-14400).
  • Nullable fields are always present and explicitly null rather than omitted.
  • meta.tzdb_version records the IANA time zone database release behind the response, so you always know the vintage of the data. Live fields are computed per request and never stale.

List responses also include the standard pagination fields (from, to, last_page, path, and a meta.links array of page links), trimmed from the examples for brevity.