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 and cities that use them — all computed in real time from the IANA time zone database.

The API is currently in v1 and covers time zones, abbreviations, countries, cities, and time conversion.

New here? The Quickstart takes you from zero to your first response in about two minutes.

Base URL

All endpoints live under a single versioned base URL. Every request is served over HTTPS, returns JSON, and must be authenticated:

https://api.timezone.io/v1

The API at a glance

Nine endpoints, all GET:

Endpoint What you get
/timezones Every IANA zone — filter by country, offset, abbreviation, or DST behavior.
/timezones/{iana} One zone in full live detail: current time, DST state, next transition.
/abbreviations The named layer (EST, CET, JST): codes, names, defining offsets.
/abbreviations/{code|slug} One named standard with its DST counterpart and member-zone counts.
/countries Countries and territories — filter by region or DST observance.
/countries/{iso2|slug} One country: default zone, zone/city counts, DST summary, dependencies.
/cities Major cities with their zone and live offset — searchable.
/cities/{slug} One city: live local time plus sunrise, sunset, and daylight length.
/convert Convert a moment between zones (up to 10 targets), DST folds/gaps disclosed.

Response format

Successful responses follow one envelope, whatever the endpoint:

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).

A typical list response:

{
    "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": "2025.2",
        "generated_at": "2026-06-12T09:00:00+00:00"
    },
    "links": { "first": "…", "last": "…", "prev": null, "next": null }
}

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.
  • Identifiers are case-insensitive where the underlying standard allows it: country codes (fr or FR), abbreviation codes (est or EST), and IANA names.

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. Counts and totals shown in examples reflect one tzdb release and shift slightly over time.