Business days and holiday API guide: count working days between dates

Short answer: call /v1/time/diff (or /v1/time/elapsed) with business_days=true and a holiday_country. You get a working-day count that skips weekends and that country's public holidays, for any of 249 countries and 862 calendars including regional subdivisions.

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=US" \
  -H "Authorization: Bearer $TIMELOGIC_API_KEY"

How do business-day calculations work?

TimeLogic API exposes a holiday API and business day calculator API through /v1/time/diff and /v1/time/elapsed. Add business_days=true to request a business-day count between two instants and pair it with holiday_country when public holidays should be excluded. This covers working-day counts between two dates (the classic working days API and count business days API use case) without rebuilding holiday calendars in your application. /v1/time/calendar has no business-day or holiday parameters, and there is no "add N business days" operation.

Days are counted by calendar date with the start date included and the end date excluded, so the example above counts January 2 through April 29. When a timezone is known for an endpoint (for example from_tz), its date is taken in that zone; otherwise in UTC.

What does the request look like?

from and to are embedded specifiers such as now, unix=..., or iso=.... For local ISO wall times, add the matching from_tz, to_tz, or another source hint. Then enable business-day mode (diff business days API):

GET /v1/time/diff?from=iso=2026-01-02T00:00:00Z&to=iso=2026-04-30T00:00:00Z&business_days=true&holiday_country=US

Which holiday calendars are supported?

holiday_country takes any of the 249 countries with holiday calendars (862 calendars including subdivisions), as an ISO 3166-1 alpha-2 code in any letter case. Add holiday_subdivision for a regional calendar (for example GB + ENG, CH + ZH, IN + MH, NZ + CAN), or use the combined form holiday_country=CH-ZH. Subdivision codes can contain digits, and leading zeros count (FI-01, FR-971, FR-6AE). Weekends follow each country's working week, for example Friday and Saturday in SA. Holiday data covers 1900 to 2100. The full list with every subdivision code is in holiday calendars. Both holiday parameters require business_days=true; unsupported or malformed calendars return a documented INVALID_PARAMETER error.

Results for the same range, January 2 to April 30, 2026 (from=iso=2026-01-02T00:00:00Z&to=iso=2026-04-30T00:00:00Z&business_days=true), show what each public holidays API calendar changes:

Which operation should I use?

• Use Diff between two moments when both endpoints are known and you need elapsed duration plus an optional business-day count.
• Use Elapsed since when one reference is compared with the current request time, or with an optional comparison timestamp.
• Use Calendar projection when you need year, month, day, weekday, or ISO week fields for a resolved instant (no business-day data).
• Use Add to a timestamp for ordinary day, hour, minute, or second date arithmetic. It is not a holiday-aware business-day adder.

Related guides and documentation

• Time zone conversion API guide: date math and timestamps across zones.
• World Time API guide: current time, weekday and calendar fields.
• Signed API responses: verifiable business-day results.
• Docs: diff and business days, the holiday calendar API code list, the diff endpoint reference, and the elapsed endpoint reference.