公眾 假期 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
}為實際排程情境打造
HR 排程
在跨多個國家計算休假餘額、薪資週期與班表時,自動排除公眾假期。
交易行事曆
在金融模型與回測中略過非交易日。辨識會影響結算與清算視窗的銀行假日。
物流 ETA
自動略過起運、轉運與目的地國家的假期,計算出準確的送達時間估計。
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 年的年度。