Skip to content
Endpoint guide

Diff between two moments

GET /v1/time/diffOpenAPI YAML

Absolute duration between two specifier-encoded instants, with optional business-day count.

What do I need to send?

Required / choose this first

Provide both from and to. Each value is an embedded specifier such as now, unix=..., or iso=....

Optional

Zone hints, business_days, holiday fields, format, and sign are conditional options.

Rule: Returned magnitudes are absolute; use direction to tell forward from backward.

NameNeeded?Use it for
fromRequiredStart specifier. One of: now, unix=N, unix_ms=N, iso=..., tz=..., ip=..., offset=...
toRequiredEnd specifier. Same forms as from.
from_tzConditional hintWall-clock zone hint for from=iso=... (no embedded offset).
from_ipConditional hintResolve from=iso=... wall clock via this IP's zone.
from_latPair parameterLatitude hint for from=iso=... wall clock. Pair with from_lon.
from_lonPair parameterLongitude hint for from=iso=... wall clock.
from_offsetConditional hintFixed offset hint for from=iso=... wall clock.
to_tzConditional hintWall-clock zone hint for to=iso=... (no embedded offset).
to_ipConditional hintResolve to=iso=... wall clock via this IP's zone.
to_latPair parameterLatitude hint for to=iso=... wall clock. Pair with to_lon.
to_lonPair parameterLongitude hint for to=iso=... wall clock.
to_offsetConditional hintFixed offset hint for to=iso=... wall clock.
formatOptionalDuration template using %days %hours %minutes %seconds. Each placeholder is a total, not a remainder.
business_daysOptionalSet true (or 1 / yes) to include a business_days count in the response. Counted by calendar date, start included, end excluded.
holiday_countryConditionalHoliday calendar: one of the 249 countries with holiday calendars (ISO 3166-1 alpha-2, e.g. FR, SA, CH), or a combined code such as CH-ZH or FR-6AE. Requires business_days=true. Full list: /docs#holiday-calendars.
holiday_subdivisionConditionalSubdivision code for the country, e.g. ENG (GB), ZH (CH), MH (IN), 01 (FI), 6AE (FR); digits and leading zeros are part of the code. Requires holiday_country and business_days=true. Full list: /docs#holiday-calendars.
signOptionalSet true for a signed response.

Code samples

Copy a request in your preferred language and replace YOUR_TIMELOGIC_API_KEY with your direct API key.

curl "https://api.timelogicapi.com/v1/time/diff?from=unix=1711300000&to=tz=America/New_York" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

Example response

{
  "seconds": 10195200,
  "minutes": 169920,
  "hours": 2832,
  "days": 118,
  "direction": "forward",
  "human": "2832 hours, 0 minutes, 0 seconds",
  "from": { "unix_ms": 1767312000000 },
  "to":   { "unix_ms": 1777507200000 },
  "business_days": 83
}
Additional endpoint notes

from and to are embedded specifier strings — the value itself is a key=value form:

?from=unix=1711300000&to=now ?from=iso=2026-04-16T09:00:00&from_tz=America/New_York&to=iso=2026-04-16T09:00:00&to_tz=Europe/London ?from=now&to=unix=1711300000

Selector forms (tz=..., ip=..., offset=...) inside from/to resolve to the request-time instant, which is the same in every zone, so they never change seconds or direction (from=ip=8.8.8.8&to=now is 0 seconds). They exist for symmetry, and their zone is used to pick the calendar date when counting business days. Coordinates are not a specifier (from=lat=… returns "Unsupported time specifier."); use them only as the from_lat/from_lon hint for a local iso.

curl "https://api.timelogicapi.com/v1/time/diff?from=iso=2026-01-02T00:00:00Z&to=iso=2026-04-30T00:00:00Z&business_days=true&holiday_country=FR" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

direction is forward, backward, or same. Magnitudes are absolute. seconds, minutes, hours and days are each the whole duration in that unit (rounded down), not parts of one breakdown. format=%25days%20days%20%25hours%20hours adds a formatted field; its placeholders are totals too, so a 118-day range renders as 118 days 2832 hours, not 118 days 0 hours. human is always written in hours, minutes and seconds (2832 hours, 0 minutes, 0 seconds), never in days.

Business days. With business_days=true the count uses calendar dates, start included and end excluded, so the example above returns 83 (January 2 through April 29). Each endpoint's date is taken in its own zone when one is known (from_tz/to_tz or the other hints, or a tz=/ip=/offset= specifier), and in UTC otherwise. Weekends follow the calendar's country (Friday and Saturday for SA, for example). Full rules: Diff & business days; all 249 countries and their subdivision codes: Holiday calendars.

Common errors

  • 400 INVALID_PARAMETER — missing from/to, malformed specifier ("Unsupported time specifier."), a country with no holiday calendar ("Unsupported holiday calendar.", for example LK or ZZ), an unknown subdivision ("Unknown holiday_subdivision 'XX' for country DE.", also for FI-1, which must be written FI-01), a malformed code ("Invalid holiday_country parameter." / "Invalid holiday_subdivision parameter."), or a business-day range outside 1900–2100 with a calendar ("Holiday calendar coverage is only available for years 1900-2100.").
  • 400 INVALID_TIMESTAMP — an iso/unix value inside a specifier that is malformed, not a real date, or out of range.
  • 400 INVALID_PARAMETER — holiday_subdivision without holiday_country, or holiday params without business_days=true.

When to use this endpoint

Use Diff between two moments to calculate elapsed duration between any two specifier-encoded instants. It works well for SLA counters, age calculations, countdowns, and workflows that compare a stored event time to a user-local or zone-local target.

Request model

The from and to parameters are required. Each can be now, a Unix value, an ISO value, or a selector-backed instant such as a timezone, IP, or fixed offset (which all mean "now"). Zone hints disambiguate local ISO wall times.

Business-day mode

Enable business-day counting when product logic needs calendar-aware duration instead of pure elapsed seconds. Pair it with the business-day documentation for holiday calendar and weekend assumptions.

Frequently asked questions

How do I calculate the time between two dates with an API?

Call GET /v1/time/diff with from= and to= specifiers, for example from=iso=2026-01-02T00:00:00Z&to=now. The response gives seconds, minutes, hours and days as whole totals plus a direction.

Can the difference count business days?

Yes. Add business_days=true and a holiday_country such as FR. The count uses calendar dates with the start included and the end excluded.

What does direction mean?

direction is forward, backward or same. The magnitudes are always absolute, so use direction to tell which way the range runs.