Holiday API

Public holidays by country, year, month, or day.

List published holidays and cultural observances for a country, then narrow the calendar to a month or day. Records include the date, name, regional scope, and the source calendar's substitute flag. The type field distinguishes official public holidays from cultural observance dates.

Collections always return a holidays array, including every record when multiple holidays share a date. A covered period with no matches returns an empty array. An unavailable year returns 404 with the available range. Future dates come from official publications or finite, independently reviewed current rules; they do not claim a future annual publication.

YearCopy link

GET /holiday/{country}/{year}API Explorer ↗

Year collection, for example /holiday/US/2026

GET /holiday/{country}API Explorer ↗

Current year, with optional year, month, and day query filters

Parameters

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

typestring · query · optional

Select public or observance. Omit to retain both categories and the existing public-first single-date choice. A covered category miss returns an empty array or holiday: null; a missing calendar remains 404. Unknown or repeated selectors return 400. Frozen 1.0.0 remains unchanged.

Values: public, observance

yearinteger · query · optional

Four-digit available year; defaults to the current UTC year. Must match a path year when supplied.

Range: 1 to 9999

monthinteger · query · optional

Collection month. Must match a path month when supplied.

Range: 1 to 12

dayinteger · query · optional

Collection day. Requires month and a real calendar date.

Range: 1 to 31

regionstring · query · optional

Reviewed subdivision suffix such as NSW or matching full code AU-NSW. Includes nationwide plus matching regional dates outside the US. Reviewed US states select their independent employee calendar, plus current countrywide observances when requested. Case-insensitive; unsupported or wrong-country regions return 400.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

Omit year for the current UTC year. Add month to narrow the collection.

Request

curl "https://api.parseapi.com/holiday/US/2026" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Version: 2.3.0"
Example response
{
  "country": "US",
  "year": 2026,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-01-19",
      "name": "Birthday of Martin Luther King, Jr.",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-02-14",
      "name": "Valentine's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-02-16",
      "name": "Washington's Birthday",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-03-17",
      "name": "St. Patrick's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-04-03",
      "name": "Good Friday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-04-05",
      "name": "Easter Sunday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-05",
      "name": "Cinco de Mayo",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-10",
      "name": "Mother's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-25",
      "name": "Memorial Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-06-19",
      "name": "Juneteenth National Independence Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-06-21",
      "name": "Father's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-07-03",
      "name": "Independence Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": true
    },
    {
      "date": "2026-09-07",
      "name": "Labor Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-10-12",
      "name": "Columbus Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-10-31",
      "name": "Halloween",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-11",
      "name": "Veterans Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-26",
      "name": "Thanksgiving Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-27",
      "name": "Black Friday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-24",
      "name": "Christmas Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-31",
      "name": "New Year's Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    }
  ]
}

Response fields

countryLink to countrystring
ISO2 country code
yearLink to yearinteger
Year returned
monthLink to monthinteger
Selected month, present on month and day collections
dayLink to dayinteger
Selected day of month, present on day collections
holidaysLink to holidaysarray
Every matching holiday and observance, including multiple names on one date. Empty array for a covered period with no matches
holidays[].dateLink to holidays[].datestring
Date, YYYY-MM-DD
holidays[].nameLink to holidays[].namestring
Official name, English or the official translation (France stays French)
holidays[].name_localLink to holidays[].name_localstring or null
Native form when it differs (Japan kanji, Hong Kong and Taiwan Chinese), null otherwise
holidays[].typeLink to holidays[].typestring
public for an officially designated holiday, observance for cultural dates (Halloween, Black Friday)
holidays[].regionsLink to holidays[].regionsarray or null
Subdivision codes where this record applies (GB: ENG, WLS, SCT, NIR). Null means country-wide within the calendar’s declared scope; it does not establish workplace closure
holidays[].substituteLink to holidays[].substituteboolean
Source calendar replacement or in-lieu flag. It does not establish the original occasion; reviewed actual/observed relationships are available in calendar Deep when known

MonthCopy link

GET /holiday/{country}/{year}-{month}API Explorer ↗

Month collection. Same result as ?year=2026&month=12

Request

curl "https://api.parseapi.com/holiday/US/2026-12" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Version: 2.3.0"
Example response
{
  "country": "US",
  "year": 2026,
  "month": 12,
  "holidays": [
    {
      "date": "2026-12-24",
      "name": "Christmas Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-31",
      "name": "New Year's Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    }
  ]
}

Day collectionCopy link

Use year, month, and day query filters for every holiday on a date. Day requires month. You can also add day to a month path.

Request

curl "https://api.parseapi.com/holiday/US?year=2026&month=12&day=25" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Version: 2.3.0"
Example response
{
  "country": "US",
  "year": 2026,
  "month": 12,
  "day": 25,
  "holidays": [
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    }
  ]
}

Use YYYY, YYYY-MM, or YYYY-MM-DD in paths. Months and days in paths need two digits. Invalid dates and conflicting path and query values return 400 with guidance. Matching values are allowed.

One dateCopy link

The full date path keeps its existing response. holiday is one matching record, or null for a covered date with no match. A public holiday takes priority when the date has multiple records. Use the day collection to keep every name. A missing holiday does not establish a working day.

GET /holiday/{country}/{date}API Explorer ↗

One date, YYYY-MM-DD. The holiday object, or holiday: null

Parameters

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

datestring · path · required

YYYY, YYYY-MM, or YYYY-MM-DD. Path months and days require two digits. Full dates must be real calendar dates.

Pattern: ^\d{4}(?:-\d{2}){0,2}$

typestring · query · optional

Select public or observance. Omit to retain both categories and the existing public-first single-date choice. A covered category miss returns an empty array or holiday: null; a missing calendar remains 404. Unknown or repeated selectors return 400. Frozen 1.0.0 remains unchanged.

Values: public, observance

yearinteger · query · optional

Four-digit available year; defaults to the current UTC year. Must match a path year when supplied.

Range: 1 to 9999

monthinteger · query · optional

Collection month. Must match a path month when supplied.

Range: 1 to 12

dayinteger · query · optional

Collection day. Requires month and a real calendar date.

Range: 1 to 31

regionstring · query · optional

Reviewed subdivision suffix such as NSW or matching full code AU-NSW. Includes nationwide plus matching regional dates outside the US. Reviewed US states select their independent employee calendar, plus current countrywide observances when requested. Case-insensitive; unsupported or wrong-country regions return 400.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

Example

Request

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.holiday.date("US", "2026-12-25");
console.log(result);
Example response
{
  "country": "US",
  "date": "2026-12-25",
  "holiday": {
    "date": "2026-12-25",
    "name": "Christmas Day",
    "name_local": null,
    "type": "public",
    "regions": null,
    "substitute": false
  }
}

Response fields

countryLink to countrystring
ISO2 country code
dateLink to datestring
Date checked
holidayLink to holidayobject or null
The holiday on that date (same shape as holidays[]), or null

Native namesCopy link

Japan pairs the official English name with kanji in name_local, back to 1955.

Request

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.holiday("JP", { year: 1955 });
console.log(result);
Example response
{
  "country": "JP",
  "year": 1955,
  "holidays": [
    {
      "date": "1955-01-01",
      "name": "New Year's Day",
      "name_local": "元日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-01-15",
      "name": "Coming of Age Day",
      "name_local": "成人の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-03-03",
      "name": "Hinamatsuri",
      "name_local": "ひな祭り",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-03-21",
      "name": "Vernal Equinox Day",
      "name_local": "春分の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-04-29",
      "name": "Emperor's Birthday",
      "name_local": "天皇誕生日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-05-03",
      "name": "Constitution Memorial Day",
      "name_local": "憲法記念日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-05-05",
      "name": "Children's Day",
      "name_local": "こどもの日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-07-07",
      "name": "Tanabata",
      "name_local": "七夕",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-08-15",
      "name": "Obon",
      "name_local": "お盆",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-09-24",
      "name": "Autumnal Equinox Day",
      "name_local": "秋分の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-11-03",
      "name": "Culture Day",
      "name_local": "文化の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-11-15",
      "name": "Shichi-Go-San",
      "name_local": "七五三",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-11-23",
      "name": "Labor Thanksgiving Day",
      "name_local": "勤労感謝の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-12-24",
      "name": "Christmas Eve",
      "name_local": "クリスマスイブ",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-12-25",
      "name": "Christmas",
      "name_local": "クリスマス",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-12-31",
      "name": "New Year's Eve",
      "name_local": "大晦日",
      "type": "observance",
      "regions": null,
      "substitute": false
    }
  ]
}

Downloads and working schedules

Choose a type or regionCopy link

Add type=public or type=observance to the ordinary collection or date route. Omitting type keeps both categories and the public-first single-date choice. A covered category with no match returns an empty collection or null; an unavailable year remains 404. Use region=NSW or region=AU-NSW for nationwide and matching regional dates. For the US, region selects a separate reviewed state scope; omitting it keeps federal employee dates. State dates do not inherit federal closures. Unsupported or wrong-country regions return 400.

Read or save a calendarCopy link

GET /holiday/{country}/calendarAPI Explorer ↗

Reviewed public calendar. Explicit year required

Parameters

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · required

Explicit four-digit year. Unavailable years remain 404.

Range: 1 to 9999

formatstring · query · optional

json returns the complete calendar resource. ics and csv download immutable snapshots, not live subscriptions.

Default: json

Values: json, ics, csv

regionstring · query · optional

Selects an independent US state edition, including JSON; its edition pin requires the matching state. Other countries accept region for downloads only. Portugal ICS defaults to national dates and US ICS to federal employee dates. Other regional ICS requires a region. CSV can retain the full selected edition or filter a region.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

GET /holiday/AU/calendar?year=2027

The complete holidays array uses the same six holiday fields as an ordinary lookup. Calendar scope and completeness qualify the returned dates. Unknown annual date review remains explicit. Pending dates appear only when recorded. Paid plans automatically include actual/observed date relationships and their citations only when independently reviewed. Unknown relationships do not produce placeholder fields.

GET /holiday/{country}/calendar?format=icsAPI Explorer ↗

All-day iCalendar snapshot of a reviewed calendar scope

Parameters

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · required

Explicit four-digit year. Unavailable years remain 404.

Range: 1 to 9999

formatstring · query · optional

json returns the complete calendar resource. ics and csv download immutable snapshots, not live subscriptions.

Default: json

Values: json, ics, csv

regionstring · query · optional

Selects an independent US state edition, including JSON; its edition pin requires the matching state. Other countries accept region for downloads only. Portugal ICS defaults to national dates and US ICS to federal employee dates. Other regional ICS requires a region. CSV can retain the full selected edition or filter a region.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

GET /holiday/{country}/calendar?format=csvAPI Explorer ↗

CSV with literal civil dates and reviewed scope

Parameters

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · required

Explicit four-digit year. Unavailable years remain 404.

Range: 1 to 9999

formatstring · query · optional

json returns the complete calendar resource. ics and csv download immutable snapshots, not live subscriptions.

Default: json

Values: json, ics, csv

regionstring · query · optional

Selects an independent US state edition, including JSON; its edition pin requires the matching state. Other countries accept region for downloads only. Portugal ICS defaults to national dates and US ICS to federal employee dates. Other regional ICS requires a region. CSV can retain the full selected edition or filter a region.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

GET /holiday/AU/calendar?year=2027&format=ics&region=NSW
GET /holiday/AU/calendar?year=2027&format=csv&region=NSW

ICS uses all-day civil dates with exclusive next-date ends. For most countries, a region includes national and matching regional dates. US region selects an independent state edition for JSON and downloads. iCalendar defaults to federal employee dates for the US and national dates for Portugal. Other regional iCalendar downloads require a region. CSV can omit region to keep the full selected edition. Downloads retain their edition, scope and annual date verification and return Content-Disposition. They are edition snapshots, not live subscriptions. Fetch a newer edition to receive corrections.

List a date windowCopy link

GET /holiday/{country}/rangeAPI Explorer ↗

Inclusive from and to, across up to 731 civil dates

Parameters

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

fromstring · query · required

Real inclusive civil start date, chosen by the caller.

tostring · query · required

Real inclusive civil end date; at most 731 dates including both bounds.

typestring · query · optional

Current defaults to public plus observance. Select one category.

Values: public, observance

regionstring · query · optional

Nationwide plus matching regional rows outside the US. A reviewed US state selects its independent annual public calendar. Current countrywide observances are included when requested. The region must be represented in every reached annual public calendar; unsupported annual regional scope returns 400.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

GET /holiday/AU/range?from=2026-12-25&to=2027-01-03&region=NSW&type=public

Every matching record remains in holidays, including separate names sharing a date. calendars identifies the year, scope and completeness of every reached calendar. Current windows include public holidays and curated observances unless type selects one. Missing any required year returns 404; unmatched review evidence returns 503. There is no partial result or silent truncation.

Count working daysCopy link

GET /holiday/{country}/workdaysAPI Explorer ↗

Inclusive interval with an explicit working week

Parameters

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

fromstring · query · required

First date, included in the result.

tostring · query · required

Last date, included in the result. Must be on or after from and at most 365 days later.

weekendstring · query · required

Explicit comma-separated weekday digits: 0 is Sunday and 6 is Saturday. Use none for no weekend days. No country default is supplied.

Pattern: ^(?:none|[0-6](?:,[0-6])*)$

regionstring · query · optional

Reviewed subdivision suffix or matching full code. Required for regional calendars except Portugal and the US: omit for Portugal national holidays or US federal employee holidays. PT-20 selects Azores; PT-30 Madeira. Reviewed US states select their independent employee calendar and edition.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

working_datesstring · query · optional

Up to 50 comma-separated YYYY-MM-DD dates within the requested interval to treat as working.

closed_datesstring · query · optional

Up to 50 comma-separated YYYY-MM-DD dates within the requested interval to treat as closed. A date cannot appear in both override lists.

work_profilestring · query · optional

Explicit official profile: tw-government-office for TW2027 government administrative offices (published per-date status replaces the supplied weekend), cn-national-adjustments for CN2026 national breaks/make-up workdays, ru-five-day-adjustments for RU2027 five-day national adjustments, or by-five-day-adjustments for BY2027 prescribed five-day adjustments (CN/RU/BY require weekend=0,6). RU2027 and BY2027 scheduling require their profiles; missing selection returns 400. BY2027 makes May 8 working and May 10 a rest day, excluding employer alternative Saturdays, six-day and shift schedules. Every requested year must have a matching profile. No default; wrong country/year/weekend 400, changed bound calendar edition or scope 503. Caller date overrides take precedence.

Values: tw-government-office, cn-national-adjustments, ru-five-day-adjustments, by-five-day-adjustments

GET /holiday/AU/workdays?from=2027-01-01&to=2027-01-31&region=NSW&weekend=0,6

Supply a range of up to 366 dates and your weekend policy. weekend=0,6 means Sunday and Saturday; weekend=none means no weekend dates. The US uses federal employee holidays unless a reviewed state is selected. Other regional calendars require a region. Portugal retains its national statutory baseline without region; select region=20 for Azores or region=30 for Madeira holidays. Applicable public holidays close dates; observances do not. The ordinary response completes the count with workdays, the selected policy and compact calendar references. Paid plans automatically include days, each considered date and its reason.

Response fields

countryLink to countrystring
ISO2 country code
fromLink to fromstring
First date, included
toLink to tostring
Last date, included; at most 366 dates
regionLink to regionstring or null
Selected subdivision suffix or null
policy.weekendLink to policy.weekendarray
Explicit weekday numbers, 0 Sunday through 6 Saturday
policy.working_datesLink to policy.working_datesarray
Caller overrides; omitted when empty
policy.closed_datesLink to policy.closed_datesarray
Caller closures; omitted when empty
policy.work_profileLink to policy.work_profileobject
Only when selected: official profile ID, declared scope and retained annual profile editions
workdaysLink to workdaysinteger
Working-day count under the supplied schedule
calendarsLink to calendarsarray
Every used year’s scope, completeness and any unverified or pending qualification; unresolved relevant dates stop the calculation

Included date details

daysLink to daysarray
Included on paid plans: each date, working flag and reason

Find a working dateCopy link

GET /holiday/{country}/business-dateAPI Explorer ↗

Add or subtract working days from a start date

Parameters

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

start_datestring · query · required

Real civil start date. The default excludes this date from the count.

business_daysinteger · query · required

Signed integer offset. Use a negative value to count backward, or zero to retain the start.

Range: -366 to 366

weekendstring · query · required

Explicit comma-separated weekday digits: 0 is Sunday and 6 is Saturday. Use none for no weekend days. No country default is supplied.

Pattern: ^(?:none|[0-6](?:,[0-6])*)$

include_start_dateboolean · query · optional

Count the start as the first date only when it is working. The default excludes it. Zero always leaves the start unchanged.

Default: false

regionstring · query · optional

Reviewed subdivision suffix or matching full code. Required for regional calendars except Portugal and the US: omit for Portugal national holidays or US federal employee holidays. PT-20 selects Azores; PT-30 Madeira. Reviewed US states select their independent employee calendar and edition.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

working_datesstring · query · optional

Up to 50 comma-separated YYYY-MM-DD caller overrides in the selected direction, within 732 calendar days of start_date. A date cannot appear in both override lists.

closed_datesstring · query · optional

Up to 50 comma-separated YYYY-MM-DD caller overrides in the selected direction, within 732 calendar days of start_date. A date cannot appear in both override lists.

work_profilestring · query · optional

Explicit official profile: tw-government-office for TW2027 government administrative offices (published per-date status replaces the supplied weekend), cn-national-adjustments for CN2026 national breaks/make-up workdays, ru-five-day-adjustments for RU2027 five-day national adjustments, or by-five-day-adjustments for BY2027 prescribed five-day adjustments (CN/RU/BY require weekend=0,6). RU2027 and BY2027 scheduling require their profiles; missing selection returns 400. BY2027 makes May 8 working and May 10 a rest day, excluding employer alternative Saturdays, six-day and shift schedules. Every requested year must have a matching profile. No default; wrong country/year/weekend 400, changed bound calendar edition or scope 503. Caller date overrides take precedence.

Values: tw-government-office, cn-national-adjustments, ru-five-day-adjustments, by-five-day-adjustments

GET /holiday/US/business-date?start_date=2027-01-05&business_days=-1&weekend=0,6

The signed count accepts −366 through 366. Negative numbers count backward. The start is excluded unless include_start_date=true and it is working. Zero preserves the start after checking its calendar. The walk is bounded to 732 calendar days. The response returns the reached date; paid profile detail explains each considered date and whether it counted.

Both schedule routes accept up to 50 explicit working_dates and closed_dates each. Overrides take precedence; contradictory overrides return 400. Official profiles are selected explicitly: Taiwan government offices in 2027 replace weekend classification with the published daily schedule, while China national adjustments in 2026 apply announced breaks and make-up workdays to an explicit Saturday/Sunday weekend. Their declared scope excludes employer-specific rules. Missing years return 404; unverified or relevant unresolved dates return 503. Uruguay includes designated working holidays, so these calculations return 503 until a reviewed closure policy is available. Its date and calendar lookups remain available.