公共 节假日 API
一次 API 调用即可查询 100+ 个国家、任意年份的公共节假日。完全本地计算——无外部数据源，也不会有速率限制带来的意外。
集成指南
复制代码片段，替换你的 API 密钥，运行即可。适用于任何 HTTP 客户端——下方提供 cURL、JavaScript 和 Python 示例。
/api/holidayshttps://www.apipick.comGet all public holidays for a country and year
countrystring必填ISO 3166-1 alpha-2 country code US
yearinteger可选4-digit year (defaults to current year) 2026
curl -X GET "https://www.apipick.com/api/holidays" \
-H "x-api-key: YOUR_API_KEY"{
"success": true,
"code": 200,
"message": "Holidays retrieved successfully",
"data": {
"country": "US",
"country_name": "United States",
"year": 2026,
"total": 11,
"holidays": [
{
"date": "2026-01-01",
"name": "New Year's Day"
},
{
"date": "2026-01-19",
"name": "Martin Luther King Jr. Day"
},
{
"date": "2026-02-16",
"name": "Presidents' Day"
},
{
"date": "2026-05-25",
"name": "Memorial Day"
},
{
"date": "2026-07-03",
"name": "Independence Day (observed)"
},
{
"date": "2026-09-07",
"name": "Labor Day"
},
{
"date": "2026-10-12",
"name": "Columbus Day"
},
{
"date": "2026-11-11",
"name": "Veterans Day"
},
{
"date": "2026-11-26",
"name": "Thanksgiving Day"
},
{
"date": "2026-12-25",
"name": "Christmas Day"
}
]
},
"credits_used": 1,
"remaining_credits": 99
}为真实排程场景而生
人力资源排程
在跨多个国家计算休假余额、薪资周期和排班表时，自动排除公共节假日。
交易日历
在金融模型和回测中跳过非交易日。识别影响结算和清算窗口的银行假日。
物流预计到达时间
自动跳过始发地、中转地和目的地国家的节假日，计算准确的送达预估。
n8n 自动化
接入 n8n 或 Zapier 工作流，为对时间敏感的操作设置闸门——在法定节假日不发送邮件或报告。
HolidayAPI 与 Nager.Date 的替代方案
当年数据、未来年份规划，以及生产级 SLA——没有免费额度的年份锁定，也没有社区项目的可靠性风险。
HolidayAPI | Nager.Date | API Pick ✓ | |
|---|---|---|---|
| 免费额度 | 仅限上一年 | 免费（无 SLA） | 注册赠送 100 积分 |
| 当年数据 | 仅付费套餐 | ✓ | ✓ |
| 未来年份数据 | 仅付费套餐 | ✓（有限） | ✓ 最多 +10 年 |
| 历史数据（1900 年起） | 仅付费套餐 | 部分支持 | ✓ 自 1900 年起 |
| 生产级 SLA | 仅付费套餐 | ✗ 社区项目 | ✓ |
| 覆盖国家 | ~100 | ~110 | 100+ |
| 开始无需信用卡 | ✗ | ✓ | ✓ |
| 积分 / 请求会过期吗？ | 年度套餐 | N/A | 永不过期 |
| 可用于 AI 智能体 / LLM | 部分支持 | 部分支持 | ✓ 原生 JSON |
HolidayAPI 的免费额度陷阱
HolidayAPI 的免费套餐被刻意限制为仅限上一个日历年。需要查询当年节假日，或为 2027 年的休假安排提前规划？你必须升级到付费套餐。对于任何排程或自动化场景，这都让免费额度从第一天起就形同虚设。
Nager.Date 的可靠性风险
Nager.Date 是一个由社区维护的开源项目——可免费使用，但没有正常运行时间 SLA、没有支持合同，也不保证持续可用。在它之上搭建薪资系统或物流管线的团队，曾因意外停机或弃用而吃过亏。用来做原型尚可，但不适合生产环境。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| data.country | string | ISO 3166-1 alpha-2 国家代码（大写） |
| data.country_name | string | 完整的英文国家名称 |
| data.year | integer | 查询的日历年 |
| data.total | integer | 该年份的公共节假日数量 |
| data.holidays | array | 按日期排序的节假日对象列表 |
| data.holidays[].date | string | YYYY-MM-DD 格式的节假日日期 |
| data.holidays[].name | string | 节假日的官方名称 |
| credits_used | integer | 本次请求扣除的积分 |
| remaining_credits | integer | 你账户中剩余的积分 |
速率限制
限流按 API 密钥计，采用 60 秒滑动窗口。触发限制时会返回干净的 429，并带 Retry-After 响应头。
120req/min
按 API 密钥、按端点计。60 秒滑动窗口。
3concurrent
每个 API 密钥的最大同时进行中请求数。
X-RateLimit-Limit每分钟允许的最大请求数X-RateLimit-Remaining当前窗口内剩余的请求数X-RateLimit-Reset当前窗口重置前的秒数Retry-After重试前需等待的秒数（仅在 429 时）HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 12
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded: 120 requests/minute per API key. Retry after 12s.",
"retry_after": 12
}常见问题
问： 支持哪些国家？
答： 通过开源的 python-holidays（vacanza）库支持 100+ 个国家。其中包括美国、英国、德国、法国、日本、中国、澳大利亚、加拿大、印度、巴西，以及欧洲、亚洲、拉丁美洲和非洲的大部分国家。请使用有效的 ISO 3166-1 alpha-2 代码（如 US、GB、DE）。
问： 我能往前和往后查询多久？
答： 你可以查询从 1900 年至未来 10 年内的任意年份。历史节假日是根据当时生效的规则计算的，因此结果反映的是真实的历史节庆，而非用今天的规则倒推。
问： 包含地区／州级节假日吗？
答： 该端点仅返回全国性公共节假日。州、省或地区特有的节庆（如美国各州节假日、德国各联邦州节假日）不包含在默认响应中。如果你需要次级行政区级别的节假日数据，请联系我们。
问： AI 智能体能将其作为工具使用吗？
答： 可以。该端点接受两个查询参数（country 和 year）并返回结构化的 JSON 数组——可直接定义为 OpenAI、Claude、LangChain 或任意智能体框架的函数工具。非常适合需要跨多个国家推理工作日的排程智能体。
在 Claude Code 与 AI 智能体中使用公共节假日
安装官方 Claude Code 技能，直接在你的 AI 编程智能体中查询 100+ 个国家的公共节假日——通过自然语言获取排序后的日期、官方名称和数量。
用自然语言向你的 AI 智能体提问
兼容的平台
用于 APIpick 公共节假日 API 的 Claude Code 技能
为 100+ 个国家返回按日期排序的节假日列表，附官方英文名称和总数。支持从 1900 年至未来 10 年的年份。