Docs / Time and dates / Convert time between timezones

Convert time between timezones

Convert a date-time from one IANA timezone to another, including the local times that do not exist and the ones that happen twice when clocks change.

curl "https://agent-helper.org/time/convert?value=2026-09-15T14:00&from=Europe/Moscow&to=America/New_York"
2026-09-15T07:00:00-04:00
# type: computed
# from: 2026-09-15T14:00:00+03:00 Europe/Moscow (MSK, UTC+03:00, standard time)
# to: America/New_York (EDT, UTC-04:00, daylight saving time in effect)
# utc: 2026-09-15T11:00:00Z
# tzdata: 2026d

The trap

A timezone conversion looks like arithmetic: take the offset of one zone, subtract it, add the offset of the other. That works for most of the year and fails on exactly the days that matter, because an offset belongs to an instant, not to a place.

When clocks go forward, a stretch of local time is skipped. In Berlin on 29 March 2026 the clocks jump from 02:00 to 03:00, so 02:30 never happens there. When clocks go back, a stretch repeats: on 25 October 2026 Berlin passes through 02:30 twice, an hour apart, first at UTC+02:00 and then at UTC+01:00.

Most converters do not mention either case. Libraries resolve them silently, and each resolves them its own way. Python's zoneinfo takes the first of two repeated times unless fold=1 is set, and gives a skipped time an offset that does not survive a round trip. pytz without is_dst quietly uses standard time. JavaScript's Temporal moves a nonexistent time forward by the length of the gap. Every one of these results is a well-formed timestamp, and none of them says it was a guess.

The damage appears later and somewhere else: a meeting booked for 02:30 that lands an hour off, a nightly job that runs twice on the night the clocks go back, two logs that disagree by exactly one hour for one hour a year. Because the error exists only near a transition, tests written in June do not catch it.

Two habits produce the same kind of error on ordinary days. Reading a time without an offset as UTC turns 14:00 into an instant nobody meant. Using abbreviations picks one of several zones that share a name: IST is in use in India, Ireland and Israel.

The problem becomes visible only when a converter reports what it did: which offset it applied to the input, whether daylight saving time was in effect, and whether the local time was unique.

What this endpoint does

A value without an offset is not an instant, so it needs from= with an IANA zone; UTC is never assumed. A local time that falls into a gap is refused with a 400 that names the zone and both offsets. A local time that occurs twice is refused as well, unless the request settles it with ambiguous=earlier or ambiguous=later. A value that carries its own offset or Z is converted as it stands.

Each answer shows the input as resolved, with its offset, abbreviation and daylight saving state, the target zone in the same terms, the instant in UTC, and the version of the IANA timezone database behind the result. Zones are IANA names such as America/New_York; an abbreviation such as IST is refused rather than matched to one of the zones it could mean.

Parameters

NameRequiredMeaning and valuesDefaultLimit
valueyesISO 8601 date-time; offset optional if from= is given—64 characters
fromnoIANA timezone of value when it has no offset—1024 bytes
toyestarget IANA timezone—64 characters
ambiguousnofor a wall-clock time that occurs twice (clocks go back): earlier or later
one of earlier, later		—1024 bytes

The whole path and query together are capped at 2048 bytes. Every parameter has the same meaning under /v1/time/convert.

Examples

A local time that happens twice (error)

curl "https://agent-helper.org/time/convert?value=2026-10-25T02:30&from=Europe/Berlin&to=America/New_York"
error: 400 bad parameter 'value'
parameter: value
problem: 2026-10-25T02:30:00 occurs twice in Europe/Berlin: once at UTC+02:00 and again at UTC+01:00 (clocks go back)
hint: add ambiguous=earlier or ambiguous=later, or give the instant with an explicit offset
[the rest of this error repeats the parameter list above]

The same time, with the choice stated

curl "https://agent-helper.org/time/convert?value=2026-10-25T02:30&from=Europe/Berlin&to=America/New_York&ambiguous=later"
2026-10-24T21:30:00-04:00
# type: computed
# from: 2026-10-25T02:30:00+01:00 Europe/Berlin (CET, UTC+01:00, standard time)
# to: America/New_York (EDT, UTC-04:00, daylight saving time in effect)
# utc: 2026-10-25T01:30:00Z
# tzdata: 2026d

A local time that never happens (error)

curl "https://agent-helper.org/time/convert?value=2026-03-29T02:30&from=Europe/Berlin&to=America/New_York"
error: 400 bad parameter 'value'
parameter: value
problem: 2026-03-29T02:30:00 does not exist in Europe/Berlin: clocks skip that wall-clock time (daylight-saving transition; offset changes from UTC+01:00 to UTC+02:00)
hint: choose a time outside the gap, or give the instant with an explicit offset
[the rest of this error repeats the parameter list above]

An instant that carries its own offset

curl "https://agent-helper.org/time/convert?value=2026-09-15T14:00:00Z&to=Asia/Kolkata"
2026-09-15T19:30:00+05:30
# type: computed
# from: 2026-09-15T14:00:00Z UTC+00:00
# to: Asia/Kolkata (IST, UTC+05:30, standard time)
# utc: 2026-09-15T14:00:00Z
# tzdata: 2026d

An abbreviation instead of a zone (error)

curl "https://agent-helper.org/time/convert?value=2026-09-15T14:00&from=IST&to=UTC"
error: 400 bad parameter 'from'
parameter: from
problem: 'IST' is not an IANA timezone name
hint: IST is an abbreviation, not a timezone; it is used for India, Ireland and Israel, for example Asia/Kolkata, Europe/Dublin, Asia/Jerusalem. A zone name also carries the daylight-saving rules
example: /time/convert?value=2026-09-15T14:00&from=Europe/Moscow&to=America/New_York
[the rest of this error repeats the parameter list above]

Limits and provenance

Rate class light (light computations: conversion, validation, dates, encodings, text, networks, geometry): 120 requests a minute per address, bursts of 30; wider limits apply per network and per autonomous system. Current values: /limits.

Answers are marked # type: computed; successful ones are served with Cache-Control: public, max-age=86400.

Computed locally; no external data source is involved.

Related