Build holiday-aware schedules without guessing dates

Choose the right holiday, business-day and timezone operation; audit every skipped date; and handle partial national calendars without overstating coverage.

The task: Calculate a deadline or available work window around national holidays, then preserve enough evidence to explain the result.
Review state: September 15, 2026

Direct answer

Use Business Days for deadline arithmetic, Holidays for the source calendar and Timezones for wall-clock ambiguity. Pass a country and explicit dates, inspect the skipped-day or calendar ledger, and stop when the country is marked partial unless your product can tolerate omitted lunar or government-announced dates.

Decision support

Choose the route by the job

When you need	Choose	Why
List or check a national holiday	/holidays	It exposes the calendar, coverage flag and per-country official source rather than reducing the answer to a workday count.
Add, subtract or count working days	/business-days	It applies the same public-holiday engine plus the country's weekly rest days and reports what was skipped.
Turn a local wall clock into an instant	/timezones	resolve-local exposes zero, one or two candidates for DST gaps, ordinary times and folds instead of guessing.
Populate a scheduler UI with fake events	/calendar-events	It supplies mock timed or all-day records; it does not decide whether a real date is open for business.

Which operation answers the scheduling question?

Use /add for a due date, /between for a count and /calendar when a human or test needs to audit each included date.

Business-day arithmetic is easy to get wrong at interval boundaries. On /add the start date is not counted by default; includeStart=true changes that only when the start is a business day. On /between the default interval is [from, to): the first boundary is included and the last is excluded. The calendar route is different again: it returns every date in an inclusive range.

Choose the operation before writing the request and keep its boundary flags beside the result. A count without includeStart/includeEnd is ambiguous when copied into a ticket or spreadsheet. A calendar ledger costs more bytes but is the best debugging artifact because each date carries an explicit classification and holiday details.

How do you decide whether a country is safe to schedule?

Read the country index first. Complete means the national rules in scope are represented; partial means named holidays are deliberately omitted and business-day totals may be too high.

The holiday engine currently covers 61 national calendars. Ten are marked partial because some lunar, Hijri or annually announced dates are excluded rather than guessed. Every Holidays response for those countries carries a warning, and every Business Days response states the direction of the risk: a missing holiday can make the calculated business-day total too high.

Coverage is national, not regional. State, province, canton, municipality and employer-specific closure days are outside this contract. A complete national row is therefore not a complete leave calendar for every user. If regional closure matters, combine this answer with a separately sourced regional calendar; do not relabel the national answer as local truth.

01

Read /api/holidays/countries

Confirm the country is supported, inspect coverage and coverageNote, and retain the cited official government source.
02

Use explicit calendar dates

Business Days accepts dates from 2020 through 2052. Keep the request inside the ruleset's verified range and inspect any warning.
03

Run the arithmetic and the audit ledger

Use /add or /between for the application result, then /calendar around the boundary when the outcome needs explanation or regression coverage.
04

Resolve the display time separately

A business date is not an instant. Use an IANA zone and resolve-local when a local time can fall in a DST gap or fold.

Why keep business dates separate from timezone conversion?

A business-day result is a civil date. Attach a wall-clock time and IANA zone only after the date is selected, then resolve ambiguity explicitly.

Holiday and Business Days operations classify YYYY-MM-DD calendar dates. Timezones /resolve-local answers a different question: which absolute instant, if any, corresponds to a naive local timestamp in one zone? During a spring-forward gap there can be no candidate; during an autumn fold there can be two. The default disambiguation rejects rather than chooses silently.

Calendar Events is useful after that distinction is understood. Its timed records are absolute UTC instants with a display timezone; its all-day records are date labels with an exclusive end. It is mock UI data, not a holiday engine and not a vendor-specific calendar schema.

Country support and coverage were checked before the business-day calculation.
The interval boundary rule is written next to the result.
Warnings are treated as data-quality signals, not discarded from the envelope.
Regional or employer closures are added from another source when required.
A local wall-clock time is resolved through an IANA zone after the business date is selected.

Working requests

Run the concrete examples

Move one US business day across the observed July 4 closure

Returns the next eligible business date and separately counts calendar days, weekend dates and public or observed holidays skipped.

curl request

curl -s 'https://randomapi.dev/api/business-days/add?country=US&start=2026-07-02&days=1'

Inspect the response

result is 2026-07-06 for this documented case.
One business day spans four calendar days, skipping two weekend dates and one holiday.
includeStart resolves to false, so 2026-07-02 is the starting point rather than day one.

Audit Denmark's Christmas work calendar

Returns one inclusive row per date with an exclusive business, weekend or holiday classification and any actual or observed holiday labels.

curl request

curl -s 'https://randomapi.dev/api/business-days/calendar?country=DK&from=2026-12-23&to=2026-12-31'

Inspect the response

The nine days reconcile as six business days, two weekend days and one holiday day.
2026-12-26 is classified as a weekend while retaining the Second Day of Christmas detail.
meta.params pins the explicit DK range 2026-12-23 through 2026-12-31.

Material limits

Caveats that change the decision

Business Days is bounded to 2020–2052. Holidays can compute a broader Gregorian range, but years outside a country's verified rule window carry a warning and should not be treated as current law.
The calculation excludes national public and observed substitute days. Bank-only days, observances and regional closures are not business-day exclusions.
For partial calendars, omitted holidays make workday totals too high. The response warning names the missing scope; it is material, not informational decoration.
A timezone identifier is not a holiday jurisdiction, and a country code is not enough to resolve a local wall clock through DST.