日历 API 参考
通过REST和MCP提供年度公共假日、日期查询和下一假日请求。
公开测试版已上线
使用你的 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 | 明确的 observed/substitute 状态。Null 表示未知，不表示 false。 |
普通假日对象包含全部七个字段。每个响应还包含覆盖声明，其中有 scope、nationwide 和 subdivision_codes，即使日期查询结果为空也会包含。请求 ID 和配额仍保留在标头中。成功响应正文不包含来源 URL 和数据摄取检查时间。
覆盖范围和限制
| 国家 | 2026 | 2027 | 已发布的官方数据和文档说明来源、范围、期间与限制。 |
|---|---|---|---|
ARG | 尚不可用 | 尚不可用 | 来源审查进行中 |
AUS | 可用 | 可用 | 仅限新南威尔士州：区域公共假日和银行假日 |
BRA | 尚不可用 | 尚不可用 | 来源审查进行中 |
CAN | 尚不可用 | 尚不可用 | 来源审查进行中 |
CHN | 可用 | 尚不可用 | 国家假日休息日；不包括补班工作日 |
FRA | 可用 | 可用 | 常见的全国法定假日；不包括地区性增加的假日 |
DEU | 尚不可用 | 尚不可用 | 来源审查进行中 |
IND | 尚不可用 | 尚不可用 | 来源审查进行中 |
IDN | 可用 | 尚不可用 | 全国假日和集体休假分别标注 |
ITA | 尚不可用 | 尚不可用 | 来源审查进行中 |
JPN | 可用 | 可用 | 全国公共假日 |
MEX | 尚不可用 | 尚不可用 | 来源审查进行中 |
KOR | 尚不可用 | 尚不可用 | 来源审查进行中 |
RUS | 尚不可用 | 尚不可用 | 来源审查进行中 |
SAU | 尚不可用 | 尚不可用 | 来源审查进行中 |
ZAF | 尚不可用 | 可用 | 全国公共假日；不包括仅限学校的假日 |
TUR | 尚不可用 | 尚不可用 | 来源审查进行中 |
GBR | 可用 | 可用 | 英格兰和威尔士、苏格兰及北爱尔兰的银行假日 |
USA | 可用 | 可用 | 联邦雇员假日及补休日；不包括州假日 |
目标仍为十九个国家。澳大利亚目前仅覆盖新南威尔士；法国不含额外地区性节假日；美国日历覆盖联邦雇员；英国银行假日保留已发布的三个地区划分；中国不含补班日，印度尼西亚将国定假日与集体休假分开。
已发布年份包含 1–400 个事件。缺失或撤回的覆盖范围会返回 503 calendar_coverage_unavailable。按日期查询成功时，仅在该年份已发布的情况下才可能返回空数组。公共假日不代表银行或交易所必然休市。
成功调用（包括空日期结果）每次消耗一个共享月度请求。错误不消耗月度额度；短窗口限流仍适用。 阅读共享错误与配额合约.