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

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": "2025.2",
        "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:

1. An IANA identifier — America/New_York, case-insensitive. Percent-encode + as %2B in zones like Etc/GMT%2B5.
2. A curated shorthand — pt, est, ist: common-usage answers (ist resolves to India).
3. A named time-zone slug or code — eastern-standard-time, jst.
4. A city slug — tokyo.
5. A country slug — japan.

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"

A code shared by several named zones, or a country with several timezones, 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.