Convert

Convert a moment between timezones — one source, up to ten targets, with daylight-saving folds and gaps disclosed instead of silently resolved.

At a glance

GET /v1/convert?from=America/New_York&to=Europe/London,Asia/Tokyo&at=2026-06-19T15:00:00

Parameter	Required	Description
`from`	yes	One location token (see Accepted tokens).
`to`	yes	1–10 comma-separated tokens. Duplicates are echoed; order is preserved.
`at`	no	The moment to convert (see The `at` parameter). Defaults to now.
`resolution`	no	`earliest` (default), `latest`, or `reject` — how an ambiguous or skipped wall time is handled.

Example — a 3 pm New York meeting, checked against three offices

The product team is in New York; engineering is split across London, Tokyo, and Sydney. What does "Friday at 3 pm" mean for everyone? A naked at is read as wall-clock time in from's zone:

curl "https://api.timezone.io/v1/convert?from=America/New_York&to=Europe/London,Asia/Tokyo,Australia/Sydney&at=2026-06-19T15:00:00" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
    "data": {
        "from": {
            "iana": "America/New_York",
            "datetime": "2026-06-19T15:00:00-04:00",
            "utc_offset": "-04:00",
            "utc_offset_seconds": -14400,
            "abbreviation": "EDT",
            "name": "Eastern Daylight Time",
            "is_dst": true,
            "links": { "self": "https://api.timezone.io/v1/timezones/America/New_York" }
        },
        "to": [
            {
                "iana": "Europe/London",
                "datetime": "2026-06-19T20:00:00+01:00",
                "utc_offset": "+01:00",
                "utc_offset_seconds": 3600,
                "abbreviation": "BST",
                "name": "British Summer Time",
                "is_dst": true,
                "links": {
                    "self": "https://api.timezone.io/v1/timezones/Europe/London"
                }
            },
            {
                "iana": "Asia/Tokyo",
                "datetime": "2026-06-20T04:00:00+09:00",
                "utc_offset": "+09:00",
                "utc_offset_seconds": 32400,
                "abbreviation": "JST",
                "name": "Japan Standard Time",
                "is_dst": false,
                "links": { "self": "https://api.timezone.io/v1/timezones/Asia/Tokyo" }
            },
            {
                "iana": "Australia/Sydney",
                "datetime": "2026-06-20T05:00:00+10:00",
                "utc_offset": "+10:00",
                "utc_offset_seconds": 36000,
                "abbreviation": "AEST",
                "name": "Australian Eastern Standard Time",
                "is_dst": false,
                "links": {
                    "self": "https://api.timezone.io/v1/timezones/Australia/Sydney"
                }
            }
        ],
        "utc": "2026-06-19T19:00:00Z",
        "ambiguity": { "is_ambiguous": false, "is_skipped": false }
    },
    "meta": {
        "tzdb_version": "2026d",
        "generated_at": "2026-06-12T09:00:00+00:00"
    }
}

The bad news for the meeting: it is 4 am Saturday in Tokyo and 5 am in Sydney — and every datetime above said so with its offset attached, all pinned to the single utc instant.

Accepted tokens

from and to accept, in resolution order:

An IANA identifier — America/New_York, case-insensitive (America/New York works too). Percent-encode + as %2B in zones like Etc/GMT%2B5.
A curated shorthand — pt, est, ist, Eastern Time: common-usage answers (ist resolves to India).
A UTC offset — UTC+2, GMT-5, +02:00, -0500. Whole-hour offsets resolve to the fixed-offset zone (UTC+2 is Etc/GMT-2, with the POSIX sign flip IANA uses; UTC+0 is UTC). A fixed offset never observes DST, and since it has no /timezones entry its links.self is null. Offsets with minutes (UTC+05:30) have no fixed-offset zone and return 422: pass a city on that offset instead (kolkata).
A named time-zone slug or code — eastern-standard-time, jst.
A city — tokyo, New York. Cities that share a name use the same tokens as /cities: barcelona is Spain, barcelona-ve is Venezuela.
A country — its name (japan, United Kingdom), ISO 3166 alpha-2 or alpha-3 code (jp, jpn), or a common short name (uk, uae). A country resolves to its default_timezone, even when it spans several zones: de is Europe/Berlin and usa is America/New_York. For a specific part of a multi-zone country, pass a city or IANA identifier instead (los-angeles, America/New_York).

Names are matched the way people type them: case, spaces and punctuation don't matter, so New York, new york and new-york are the same token. So this works, and means "Tokyo time to Pacific Time":

curl "https://api.timezone.io/v1/convert?from=japan&to=pt" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

And so does this — a 3 pm New York call, in the UK and at a fixed UTC+2:

curl "https://api.timezone.io/v1/convert?from=New%20York&to=uk,UTC%2B2&at=2026-06-19T15:00:00" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
    "data": {
        "from": {
            "iana": "America/New_York",
            "datetime": "2026-06-19T15:00:00-04:00",
            "utc_offset": "-04:00",
            "utc_offset_seconds": -14400,
            "abbreviation": "EDT",
            "name": "Eastern Daylight Time",
            "is_dst": true,
            "links": { "self": "https://api.timezone.io/v1/timezones/America/New_York" }
        },
        "to": [
            {
                "iana": "Europe/London",
                "datetime": "2026-06-19T20:00:00+01:00",
                "utc_offset": "+01:00",
                "utc_offset_seconds": 3600,
                "abbreviation": "BST",
                "name": "British Summer Time",
                "is_dst": true,
                "links": {
                    "self": "https://api.timezone.io/v1/timezones/Europe/London"
                }
            },
            {
                "iana": "Etc/GMT-2",
                "datetime": "2026-06-19T21:00:00+02:00",
                "utc_offset": "+02:00",
                "utc_offset_seconds": 7200,
                "abbreviation": "+02",
                "name": null,
                "is_dst": false,
                "links": { "self": null }
            }
        ],
        "utc": "2026-06-19T19:00:00Z",
        "ambiguity": { "is_ambiguous": false, "is_skipped": false }
    },
    "meta": {
        "tzdb_version": "2026d",
        "generated_at": "2026-06-12T09:00:00+00:00"
    }
}

In a query string an unencoded + arrives as a space, so to=UTC+2 and to=+02:00 are still read as positive offsets — but encoding it as %2B is the safe habit.

A code shared by several named zones returns 300 Multiple Choices with candidates to re-request from — see Errors.

The `at` parameter

Naked datetime (2026-11-01T01:30:00) — a wall-clock time in from's zone. This is the only shape where daylight-saving folds and gaps can occur. Date-only values (2026-06-15) are read the same way, as midnight wall time.
Anchored datetime (…T01:30:00-04:00, …T12:00:00+09, …Z) or Unix timestamp — an absolute instant; resolution is ignored.
Omitted — the current moment.

On the reference endpoints (/timezones/{iana}, /cities/{slug}) a naked ?at= is read as UTC; on convert it is local to from — it is the conversion input.

Response anatomy

Each side block carries the same live time-state fields as /timezones: the local datetime with its UTC offset embedded, utc_offset (+ seconds), abbreviation, the friendly name, and is_dst — all computed at the converted instant. utc is the one canonical instant every datetime in the response represents.

ambiguity is always present, with is_ambiguous (the wall time occurred twice — a DST fold) and is_skipped (it never occurred — a DST gap). When either is true, the block gains a resolution and a human-readable note:

{
    "ambiguity": {
        "is_ambiguous": true,
        "is_skipped": false,
        "resolution": "earliest",
        "note": "2026-11-01T01:30:00 occurs twice in America/New_York; returned the first occurrence. Pass resolution=latest for the other, or resolution=reject to refuse ambiguous times."
    }
}

Skipped times shift forward by the gap length unless you pass resolution=reject.

More recipes

What time is it in Tokyo right now? Omit at:

curl "https://api.timezone.io/v1/convert?from=America/New_York&to=Asia/Tokyo" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Strict mode — refuse an ambiguous fall-back time instead of resolving it (returns 422 naming both candidate instants):

curl "https://api.timezone.io/v1/convert?from=America/New_York&to=Europe/London&at=2026-11-01T01:30:00&resolution=reject" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

A Unix timestamp is an absolute instant — from only sets the left-hand rendering:

curl "https://api.timezone.io/v1/convert?from=Europe/London&to=Asia/Tokyo&at=1781870400" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

See Errors for the 300 Multiple Choices body and the full list of error responses.

Convert

At a glance#

Example — a 3 pm New York meeting, checked against three offices#

Accepted tokens#

The at parameter#