Diff between two moments
GET /v1/time/diffOpenAPI YAMLAbsolute duration between two specifier-encoded instants, with optional business-day count.
What do I need to send?
Provide both from and to. Each value is an embedded specifier such as now, unix=..., or iso=....
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. Each placeholder is a total, not a remainder. |
business_days | Optional | Set true (or 1 / yes) to include a business_days count in the response. Counted by calendar date, start included, end excluded. |
holiday_country | Conditional | Holiday 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_subdivision | Conditional | Subdivision 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. |
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": 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— missingfrom/to, malformed specifier ("Unsupported time specifier."), a country with no holiday calendar ("Unsupported holiday calendar.", for exampleLKorZZ), an unknown subdivision ("Unknown holiday_subdivision 'XX' for country DE.", also forFI-1, which must be writtenFI-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— aniso/unixvalue inside a specifier that is malformed, not a real date, or out of range.400 INVALID_PARAMETER—holiday_subdivisionwithoutholiday_country, or holiday params withoutbusiness_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.