检查某个日期是否为节假日

使用 API 完成操作

已知待检查的国家和日期时，使用日期端点。响应包含 country、coverage 和 holidays。读取 holidays 中的条目，查看适用的假日及其适用范围和行政区划，并留意多个返回条目可能对应同一个假日日期。

1. 获取你的 API 密钥 创建免费密钥，并将其保存在环境变量 NARWHAL_API_KEY 中。通过 Authorization: Bearer YOUR_KEY 发送密钥；curl 命令在身份验证请求头中使用该环境变量。
2. 请求指定国家和日期的假日 在 GET /v1/calendars/holidays/{country}/on/{date} 中使用所需的国家和日期。此请求查询英国2026年12月28日的假日。
   curl，查询单个日期的假日

   复制

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/GBR/on/2026-12-28"

3. 读取假日列表 holidays 列表为空表示请求的日期在当地不是假日。列表非空时会列出该日期的假日条目，请根据条目的范围和行政区划判断它们是否符合你需要的假日日历。
4. 查找指定日期当天或之后的假日 需要查找起始日期当天或之后的假日时，使用下一个假日端点。对于美国，from_date=2026-10-24 会在 holiday 中返回 2026 年 11 月 11 日的退伍军人节。
   curl，指定日期当天或之后的假日

   复制

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/USA/next?from_date=2026-10-24"

如果请求返回错误，请读取 application/problem+json 响应。其中的 status、code 和 detail 描述错误，request_id 标识该请求。请使用成功响应中的假日列表判断日期；错误响应不提供该假日查询结果。

使用电子表格或手动计算

如果想在不发送 API 请求的情况下查找日期，请在 Narwhal 假日日历 (英语)中查找对应国家。先选择所需日历对应的国家：圣诞节当周的示例分别使用美国和英国的结果，同一国家内的地区条目也可能影响判断。

在 Excel 或 Sheets 中，将一列假日日期命名为 Holidays，并将待检查的日期放在 A2 中。公式检查该日期是否出现在假日列中。请使用待检查国家的假日列表，因为公式只检查日期是否在你提供的日期列表中。

=COUNTIF(Holidays, A2)>0

使用美国假日列表时，公式对 2026 年 12 月 25 日返回 TRUE，对 2026 年 12 月 24 日返回 FALSE。这些结果取决于 Holidays 中的假日日期；公式本身不会向 API 请求国家日历。

列表成员检查只需判断日期是否出现在所选列表中。如果多个地区条目具有相同日期，公式仍然可以完成这一判断。要确定条目适用于哪个地区，请先读取 API 响应中的行政区划，再将其日期加入列表。

不同情况应选哪种方法

如需使用全年列表，请参阅在代码中添加假日检查。日期端点用于查询所提供的日期，下一个假日端点则接受起始日期并返回假日日期。如果要判断某个日期是否为假日，请在请求中使用该日期。如果要查询该日期当天或之后是哪个假日，请将其作为 from_date 传入。

为什么响应会多次列出同一个假日？

假日因地区而异时，API 会为每组行政区划返回一个条目。对于英国 2026 年 12 月 28 日的节礼日补假，API 返回三个条目：英格兰和威尔士合为一组，北爱尔兰和苏格兰各为一组。

合并条目的行政区划代码为 GB-ENG 和 GB-WLS，北爱尔兰为 GB-NIR，苏格兰为 GB-SCT。每个条目的范围均为 bank，且均有 observed: true。这些是同一假日日期的地区条目，因此请结合名称和行政区划分组一起查看。

observed: true 是什么意思？

它表示该日期是假日适逢周末时的补假日期。2026 年 12 月 26 日的节礼日是星期六，因此银行假日为 2026 年 12 月 28 日星期一。

在该示例中，检查日期是否在银行假日日历中时，请使用银行假日的补假日期。observed 字段说明了返回日期与假日本来日期不同的原因；这两个日期都属于同一个节礼日示例。

如何排除集体休假日？

传入 scope=national_public，即可从结果中排除印度尼西亚的集体休假日。印度尼西亚的集体休假使用独立的 collective_leave 范围，因此未使用该筛选条件的请求可能包含这些日期。

可选的 scope 筛选条件将结果限制在单个范围内。可用值包括 national_public、bank、federal_government 和 collective_leave。解读返回的假日条目前，请先选择符合所需日历的范围。

示例：美国和英国的 2026 年圣诞节当周

先查询美国的 2026 年 12 月 24 日。返回的空列表表示当天不是假日。然后查询同一国家的 2026 年 12 月 25 日：结果中出现范围为 federal_government 的圣诞节，表示当天在该日历中是假日。

对于英国，查询 2026 年 12 月 25 日，并读取范围为 bank 的圣诞节条目。然后查询 2026 年 12 月 28 日，查看节礼日补假条目。记录每个结果时，请一并保留国家、日期和范围。