六个假日操作的参考说明

操作与端点

每个操作在本站都有自己的端点：`holidays-holidays` → `POST /api/v1/holidays/holidays-holidays`，`holidays-is-workday` → `POST /api/v1/holidays/holidays-is-workday`，`holidays-workday-count` → `POST /api/v1/holidays/holidays-workday-count`，`holidays-next-holidays` → `POST /api/v1/holidays/holidays-next-holidays`，`holidays-long-weekends` → `POST /api/v1/holidays/holidays-long-weekends`，`holidays-countries` → `POST /api/v1/holidays/holidays-countries`。所有输入都放在 `body` 中。凡是接收 `body.country` 的操作，它都是两位 ISO-3166 国家代码，不区分大小写；支持 123 个国家，可通过 `holidays-countries` 获取支持的国家列表。

holidays-holidaysholidays-is-workdayholidays-workday-countholidays-next-holidaysholidays-long-weekendsholidays-countriesbodybody.country

年度列表：假日与长周末

`holidays-holidays` 与 `holidays-long-weekends` 都要求 `body.country`（字符串）和 `body.year`（1900 到 2200 之间的整数）。年度列表为每个假日返回 `date`、`name`、`localName`、`types`、`global`、`counties`、`weekday` 和 `nationwide`；长周末列表为每个窗口返回 `startDate`、`endDate`、`dayCount`、`needBridgeDay` 和 `startWeekday`。

holidays-holidaysholidays-long-weekendsbody.countrybody.year

单日检查

`holidays-is-workday` 要求 `body.country` 和 `body.date`（日期字符串，格式为 YYYY-MM-DD）。可选的 `body.weekend`、`body.types` 和 `body.subdivision` 用于调整规则。`body.types` 用于选择哪一种假日类型算作休息日；省略时只有 `Public` 算作休息日。`body.weekend` 接收逗号分隔的星期名称，例如 `Sat,Sun`；省略时周末为周六和周日（EG 与 BD 为周五和周六）。`body.subdivision` 是 ISO-3166-2 代码，例如 `US-CA`，不区分大小写；省略时按全国范围作答。`body.weekend` 与 `body.subdivision` 的无效值不会被拒绝（本站对这两个字段接受任意字符串）；无法识别的取值会被忽略并改用默认值：即默认周末，或按全国范围而不是该地区作答。结果包含 `is_workday`、`is_weekend`、`is_public_holiday`、`reasons` 和 `weekend_definition`。

holidays-is-workdaybody.datebody.weekendbody.typesbody.subdivision

统计日期区间

`holidays-workday-count` 要求 `body.country`、`body.start` 和 `body.end`，两个日期都包含在区间内。单个区间最长约 10 年。它接受与单日检查相同的三个可选输入，默认值也相同：省略 `body.types` 时只有 `Public` 算作休息日。它返回 `total_days`、`workdays`、`weekend_days`、`holiday_days` 以及区间内的假日。

holidays-workday-countbody.startbody.end

即将到来的假日与国家列表

`holidays-next-holidays` 要求 `body.country`；`body.today` 是可选的参考日期，格式为 YYYY-MM-DD，省略时使用当前 UTC 日期。无效的 `body.today` 不会被拒绝（本站对该字段接受任意字符串）；它会被忽略，并改用当前 UTC 日期。结果涵盖约未来 365 天内即将到来的公共假日，包含 `asOf`，并为每个假日给出 `daysUntil`。`holidays-countries` 不需要输入，为每个国家返回 `countryCode` 和 `name`。

holidays-next-holidaysholidays-countriesbody.today

输入约束

`body.types` 只能从 6 个取值中选一个，写法须与列出的完全一致：`Public`、`Bank`、`School`、`Authorities`、`Optional` 或 `Observance`；逗号分隔的列表和其他写法会被拒绝。国家字段不接受 `countryCode` 或 `cc` 等别名；超出范围的 `body.year` 会被拒绝。`body.weekend`、`body.subdivision` 和 `body.today` 只校验是否为字符串；无效取值如何处理见上文各节。

body.typesbody.yearbody.countrybody.weekendbody.subdivisionbody.today

列出支持的国家

POST /api/v1/holidays/holidays-countries

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {}
}

null

某年的假日

POST /api/v1/holidays/holidays-holidays

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "country": "US",
    "year": 2026
  }
}

null

检查单个日期

POST /api/v1/holidays/holidays-is-workday

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "country": "US",
    "date": "2026-01-01"
  }
}

null

查找长周末

POST /api/v1/holidays/holidays-long-weekends

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "country": "US",
    "year": 2026
  }
}

null

即将到来的假日

POST /api/v1/holidays/holidays-next-holidays

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "country": "US"
  }
}

null

统计工作日

POST /api/v1/holidays/holidays-workday-count

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "country": "US",
    "end": "2026-01-31",
    "start": "2026-01-01"
  }
}

null