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.

Name	Needed?	Use it for
`from`	Required	Start specifier. One of: now, unix=N, unix_ms=N, iso=..., tz=..., ip=..., offset=...
`to`	Required	End specifier. Same forms as from.
`from_tz`	Conditional hint	Wall-clock zone hint for from=iso=... (no embedded offset).
`from_ip`	Conditional hint	Resolve from=iso=... wall clock via this IP's zone.
`from_lat`	Pair parameter	Latitude hint for from=iso=... wall clock. Pair with from_lon.
`from_lon`	Pair parameter	Longitude hint for from=iso=... wall clock.
`from_offset`	Conditional hint	Fixed offset hint for from=iso=... wall clock.
`to_tz`	Conditional hint	Wall-clock zone hint for to=iso=... (no embedded offset).
`to_ip`	Conditional hint	Resolve to=iso=... wall clock via this IP's zone.
`to_lat`	Pair parameter	Latitude hint for to=iso=... wall clock. Pair with to_lon.
`to_lon`	Pair parameter	Longitude hint for to=iso=... wall clock.
`to_offset`	Conditional hint	Fixed offset hint for to=iso=... wall clock.
`format`	Optional	Duration template using %days %hours %minutes %seconds.
`business_days`	Optional	Set true to include a business_days count in the response.
`holiday_country`	Conditional	ISO 3166-1 alpha-2 holiday calendar (e.g. FR). Requires business_days=true. Not all countries are supported by the upstream calendar.
`holiday_subdivision`	Conditional	Subdivision code from python-holidays. Requires holiday_country and business_days=true.
`sign`	Optional	Set 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": 84
}

Additional endpoint notes

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

?from=unix=1711300000&to=tz=America/New_York
?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 in that zone, not a wall-clock time.

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. format=%25days%20days%20%25hours%20hours adds a formatted field.

Common errors

400 INVALID_PARAMETER — missing from/to, malformed specifier, or unsupported holiday_country / holiday_subdivision.
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, coordinate, or fixed offset. 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.