Time and dates

Almost every endpoint here deals with the same difficulty: a date or a time of day means nothing until it is tied to a place and a set of rules. The rules are the IANA timezone database, which changes several times a year as governments move their clocks, so each answer names the database version it was computed with.

The mistakes in this area are rarely dramatic. A duration of one month is added as thirty days; an age is computed from the number of days divided by 365.25; a timestamp without an offset is read as UTC by one program and as local time by the next; a cron schedule written in a server's local zone fires twice on the night the clocks go back. Each result is close to correct most of the time, which is why these errors survive testing.

Two conventions run through the whole group. Timezones are never assumed: where the answer depends on a zone, tz= or from= is required, and UTC is accepted only when it is named. And when a local time is ambiguous or does not exist, the request is refused with the reason rather than resolved by a silent rule. Calendar arithmetic follows the calendar, so adding one month to 31 January gives the last day of February, and the answer says how it got there.

Pages on known traps

Convert time between timezones: Convert a local time between IANA timezones. Times that never happen, or happen twice, when clocks change are refused with a reason instead of guessed.

Every endpoint in this group

/utc?[precision=]

Current UTC time, ISO 8601

precision (optional): seconds (default), milliseconds or microseconds

curl "https://agent-helper.org/utc"

/time/now?tz=

Current time in a timezone, with offset and DST state

tz: IANA timezone name

curl "https://agent-helper.org/time/now?tz=Europe/Berlin"

/time/unix?[unit=]

Current Unix time

unit (optional): s (default), ms, us or ns

curl "https://agent-helper.org/time/unix"

/time/from-unix?value=&[unit=]&[tz=]

Unix timestamp to ISO 8601 (UTC, or a timezone if given)

value: Unix timestamp; unit (optional): s (default), ms, us or ns; tz (optional): optional IANA timezone for the output

curl "https://agent-helper.org/time/from-unix?value=1789480000"

/time/to-unix?value=&[tz=]&[ambiguous=]

ISO 8601 date-time to Unix seconds

value: ISO 8601 date-time with offset, or without offset plus tz; tz (optional): IANA timezone name, e.g. Europe/Berlin; ambiguous (optional): for a wall-clock time that occurs twice (clocks go back): earlier or later

curl "https://agent-helper.org/time/to-unix?value=2026-09-15T14:00:00Z"

/time/parse?value=&[tz=]&[dayfirst=]&[ambiguous=]

Parse a date/time in almost any format into ISO 8601

value: date/time text, e.g. 'March 5 2026 2:30pm' or '05.03.2026 14:30'; tz (optional): IANA timezone to attach when the text has no offset; dayfirst (optional): true or false; required when the text is ambiguous like 03/05/2026; ambiguous (optional): for a wall-clock time that occurs twice (clocks go back): earlier or later

curl "https://agent-helper.org/time/parse?value=March%205%202026%202:30pm"

/time/convert?value=&to=&[from=]&[ambiguous=]

Convert a date-time between timezones (DST-aware)

value: ISO 8601 date-time; offset optional if from= is given; from (optional): IANA timezone of value when it has no offset; to: target IANA timezone; ambiguous (optional): for a wall-clock time that occurs twice (clocks go back): earlier or later

curl "https://agent-helper.org/time/convert?value=2026-09-15T14:00&from=Europe/Moscow&to=America/New_York"

Convert time between timezones: Convert a local time between IANA timezones. Times that never happen, or happen twice, when clocks change are refused with a reason instead of guessed.

/time/diff?from=&to=&[tz=]&[ambiguous=]

Difference between two instants or dates (exact and calendar)

from: ISO 8601 date or date-time; to: ISO 8601 date or date-time; tz (optional): IANA timezone for values without offset; ambiguous (optional): for a wall-clock time that occurs twice (clocks go back): earlier or later

curl "https://agent-helper.org/time/diff?from=2026-01-01T00:00:00Z&to=2026-09-15T14:03:22Z"

/time/add?value=&duration=&[tz=]&[ambiguous=]

Add an ISO 8601 duration to a date or date-time (calendar arithmetic)

value: ISO 8601 date or date-time; duration: ISO 8601 duration, may start with '-', e.g. P1M, PT36H, -P2W; tz (optional): IANA timezone: wall-clock arithmetic in that zone; ambiguous (optional): for a wall-clock time that occurs twice (clocks go back): earlier or later

curl "https://agent-helper.org/time/add?value=2026-01-31&duration=P1M"

/time/week?date=

ISO week, day of year, quarter and weekday of a date

date: ISO date YYYY-MM-DD

curl "https://agent-helper.org/time/week?date=2026-09-15"

/time/leap-year/{year}

Whether a year is a leap year (proleptic Gregorian)

year: year, e.g. 2028

curl "https://agent-helper.org/time/leap-year/2028"

/time/julian-day?value=&[tz=]&[ambiguous=]

Julian Day and Modified Julian Day of an instant

value: ISO 8601 date-time with offset (or plus tz); tz (optional): IANA timezone name, e.g. Europe/Berlin; ambiguous (optional): for a wall-clock time that occurs twice (clocks go back): earlier or later

curl "https://agent-helper.org/time/julian-day?value=2026-09-15T12:00:00Z"

/time/cron?expr=&tz=&[n=]&[after=]

Next firing times of a cron expression in a timezone

expr: cron expression, 5 fields (6 with seconds); tz: IANA timezone the schedule runs in; n (optional): how many firings, 1-100; after (optional): ISO 8601 instant, exclusive: firings strictly after it (default: now)

curl "https://agent-helper.org/time/cron?expr=*/15%209-17%20*%20*%20mon-fri&tz=Europe/Berlin"

/time/rrule?rule=&start=&tz=&[n=]

Occurrences of an iCalendar RRULE in a timezone

rule: RFC 5545 RRULE, e.g. FREQ=MONTHLY;BYDAY=-1FR; start: first occurrence as local date-time without offset; tz: IANA timezone of start; n (optional): how many occurrences, 1-100

curl "https://agent-helper.org/time/rrule?rule=FREQ=MONTHLY;BYDAY=-1FR&start=2026-09-25T10:00&tz=Europe/London&n=5"

/time/duration?value=&[from=]&[tz=]

Break down an ISO 8601 duration; exact seconds when unambiguous

value: ISO 8601 duration, e.g. P1Y2M10DT2H30M; from (optional): optional ISO 8601 start instant to resolve years and months; tz (optional): IANA timezone name, e.g. Europe/Berlin

curl "https://agent-helper.org/time/duration?value=P3DT4H5M"

/time/age?birth=&on=

Age in years, months and days on a given date

birth: birth date YYYY-MM-DD; on: date to compute the age on, YYYY-MM-DD

curl "https://agent-helper.org/time/age?birth=1990-05-17&on=2026-09-15"

/time/until?to=&[tz=]&[ambiguous=]

Time remaining from now until an instant

to: ISO 8601 date-time (offset, or plus tz); tz (optional): IANA timezone name, e.g. Europe/Berlin; ambiguous (optional): for a wall-clock time that occurs twice (clocks go back): earlier or later

curl "https://agent-helper.org/time/until?to=2027-01-01T00:00&tz=Europe/Berlin"

/time/business-days/add?date=&days=&country=&[region=]&[weekend=]

Add N business days to a date for a country's calendar

date: start date YYYY-MM-DD; days: business days to add (negative subtracts), max 1000; country: ISO 3166-1 alpha-2; region (optional): ISO 3166-2 subdivision to include regional holidays, e.g. DE-BY; weekend (optional): override weekend days, e.g. fri,sat

curl "https://agent-helper.org/time/business-days/add?date=2026-12-23&days=3&country=de"

/time/business-days/count?from=&to=&country=&[region=]&[weekend=]

Count business days between two dates (both inclusive)

from: first date YYYY-MM-DD, inclusive; to: last date YYYY-MM-DD, inclusive; country: ISO 3166-1 alpha-2; region (optional): ISO 3166-2 subdivision to include regional holidays, e.g. DE-BY; weekend (optional): override weekend days, e.g. fri,sat

curl "https://agent-helper.org/time/business-days/count?from=2026-12-01&to=2026-12-31&country=ru"