节假日 API 参考 | Narwhal API

公开测试版已上线

使用你的 Narwhal API 密钥访问下面已发布的国家-年份数据。REST 和 MCP 的覆盖范围相同，并共用配额。缺少数据覆盖时返回明确的错误；示例仅用于说明。

三个操作

参考	GET 端点	MCP 工具
列出节假日	`/v1/calendars/holidays/{country}/{year}`	`calendars_list_holidays`
指定日期的假日	`/v1/calendars/holidays/{country}/on/{date}`	`calendars_get_holidays_on_date`
下一个节假日	`/v1/calendars/holidays/{country}/next?from_date={from_date}`	`calendars_get_next_holiday`

使用大写国家代码，例如 IDN ，当地公历日期则采用 YYYY-MM-DD 格式。国家和日期/年份参数为必填项。可选的范围筛选条件用于选择假日类别。不支持分页或按细分地区筛选。

共享假日对象

字段	类型	含义
`date`	日期字符串	当地日历日期，而不是数据摄取时间戳。
`name`	字符串	英文或显示名称，长度为 1–256 个字符。
`local_name`	字符串或 null	如有当地名称则使用当地名称，长度为 1–256 个字符。
`subdivision_codes`	字符串数组	属于该国家的不重复代码，按序排列，例如 GB-SCT。
`nationwide`	布尔值	true 要求细分地区列表为空；false 要求列表非空。
`scope`	字符串	假日类别，例如 national_public、bank、federal_government 或 collective_leave。
`observed`	布尔值或null	明确标注是否为补休日或替代假日。Null 表示未知，不表示 false。

普通假日对象包含全部七个字段。每个响应还包含覆盖声明，其中有 scope、nationwide 和 subdivision_codes，即使日期查询结果为空也会包含。请求 ID 和配额仍保留在响应头中。成功响应正文不包含来源 URL 和数据摄取检查时间。

覆盖范围和限制

已发布的官方数据和文档说明来源、范围、期间与限制。
国家	2026	2027	已发布的覆盖范围
`ARG`	可用	尚不可用	全国节假日
`AUS`	可用	可用	仅限新南威尔士州：区域节假日和银行假日
`AUT`	可用	可用	全国节假日
`BEL`	可用	可用	全国节假日
`BRA`	可用	尚不可用	联邦政府节假日；不包括可选休假和部分停业安排
`CAN`	可用	可用	适用于受联邦监管的私营部门雇主的全国法定基准；不包括省级和联邦公务部门日历
`CHN`	可用	尚不可用	全国节假日放假安排；不包括补班工作日
`COL`	可用	可用	全国节假日
`CZE`	可用	可用	全国节假日；不包括重要纪念日、普通星期日和雇主自行安排的休业日
`DEU`	可用	尚不可用	全国共同节假日；不含各州额外假日
`DNK`	可用	可用	Danmarks Nationalbank 停业日；并非通用的雇员假日日历
`ESP`	可用	尚不可用	全国节假日
`EST`	可用	可用	全国节假日及休息日；不包括全国重要纪念日和缩短工时的工作日
`FRA`	可用	可用	常见的全国法定假日；不包括地区性增加的假日
`GBR`	可用	可用	英格兰和威尔士、苏格兰及北爱尔兰的银行假日
`HKG`	可用	可用	香港公众假期；不包括普通星期日
`HRV`	可用	可用	国家节假日和非工作日；不包括纪念日和宗派节日
`IDN`	可用	可用	全国假日和集体休假分别标注
`IND`	尚不可用	尚不可用	来源审查进行中
`IRL`	可用	可用	全国节假日；不包括雇主特定的替代休假安排和休假权益
`ITA`	可用	可用	全国法定节假日；不含地方及雇主自行安排的休假
`JPN`	可用	可用	全国节假日
`KOR`	尚不可用	尚不可用	来源审查进行中
`LTU`	可用	可用	依据《劳动法》第 123 条的全国节假日；不含地区活动
`LUX`	可用	可用	全国节假日
`LVA`	可用	可用	全国节假日；不包括纪念活动和地区性活动
`MEX`	可用	可用	全国强制劳动休息日；不包括银行、仅限州或市镇以及行业休业日
`NLD`	可用	可用	全国节假日；是否休假取决于雇佣条款
`NOR`	可用	尚不可用	Norges Bank 结算系统关闭日；并非通用的雇员假日日历
`NZL`	可用	可用	全国假日及补休日；不包括地区纪念日
`PHL`	尚不可用	尚不可用	来源审查进行中
`POL`	可用	可用	全国节假日；不包括普通星期日、地区性活动和雇主自行安排的休业日
`PRT`	可用	可用	全国强制性节假日；不包括可选假日、市级假日和地区性假日
`RUS`	尚不可用	尚不可用	来源审查进行中
`SAU`	尚不可用	尚不可用	来源审查进行中
`SGP`	可用	可用	全国节假日和来源指定的补休日
`SVK`	可用	可用	全国节假日
`SVN`	可用	可用	国家节假日和休息日；不包括非休息日纪念日和地方假日
`SWE`	可用	可用	全国节假日
`TUR`	尚不可用	尚不可用	来源审查进行中
`TWN`	可用	可用	政府机关日历；不包括私营部门停业日和市场休市日
`USA`	可用	可用	联邦雇员假日及补休日；不包括州假日
`ZAF`	可用	可用	全国节假日；不包括仅限学校的假日

可用条目仅描述列明范围，不涵盖所有地方或行业假日。年份输入允许1900–2200，但不代表提供历史覆盖。

已发布年份包含 1–400 个事件。缺失或撤回的覆盖范围会返回 503 calendar_coverage_unavailable。按日期查询成功时，仅在该年份已发布的情况下才可能返回空数组。节假日并不意味着银行必然停业或交易所必然休市。

每次成功调用（包括返回空结果的日期查询）消耗一次共用的月度请求配额。错误不消耗月度配额；短时窗口限流仍然适用。阅读通用的错误与配额接口规范。