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.

Coming from WorldTimeAPI? worldtimeapi.org has shut down. Change one hostname and your code keeps working, with no API key.

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

Ten 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.
/lookup The time zone at a latitude and longitude, on land or at sea.

OpenAPI spec and try-it

The whole contract is published as an OpenAPI 3.1 document, readable without a token: https://api.timezone.io/v1/openapi.json. Import it into Postman, Insomnia or an SDK generator, or hand it to an AI agent.

Every request example in these docs has a Try it button. It sends the request to a keyless demo copy of the API, limited to 10 requests a minute and 100 a day per IP address, so you can see real responses before you sign up. Use your own token for anything else.

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": "2026d",
        "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 names the IANA time zone database release behind the response the way IANA does (2026d), so you always know the vintage of the data. It moves to a new release once our servers install it, which can trail IANA by a few weeks. 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.
  • Pagination is ?per_page= (1–100) and ?page=.
  • Search is literal. ?q= matches a plain substring; % and _ are ordinary characters, not wildcards.

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.

Terms of use

Using the API means agreeing to the Terms of Service: they cover fair use, rate limits and commercial use, and the notice we give before a breaking change. How we handle your account data is in the Privacy Policy. Plans and monthly quotas: Rate limits.