Ngày lễ Công cộng API
Truy vấn ngày lễ công cộng cho hơn 100 quốc gia và bất kỳ năm nào trong một lượt gọi API. Tính toán hoàn toàn cục bộ — không có nguồn dữ liệu bên ngoài, không có bất ngờ về giới hạn tần suất.
Chưa có API key?
Đăng nhập vào tài khoản để tạo và quản lý API key của bạn.
Hướng dẫn tích hợp
Sao chép một đoạn mã, thay API key của bạn, chạy. Hoạt động với mọi HTTP client — các ví dụ bên dưới bằng cURL, JavaScript và Python.
/api/holidayshttps://www.apipick.comGet all public holidays for a country and year
countrystringbắt buộcISO 3166-1 alpha-2 country code US
yearintegertùy chọn4-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
}Xây dựng cho lập lịch thực tế
Lập lịch nhân sự
Tự động loại trừ ngày lễ công cộng khi tính số dư phép, chu kỳ trả lương và lịch ca làm việc trên nhiều quốc gia.
Lịch giao dịch
Bỏ qua các ngày không giao dịch trong mô hình tài chính và backtest. Nhận diện các ngày nghỉ ngân hàng ảnh hưởng đến khung thanh toán và bù trừ.
ETA Logistics
Tính ước lượng giao hàng chính xác bằng cách tự động bỏ qua ngày lễ ở quốc gia xuất phát, trung chuyển và đích đến.
Tự động hóa n8n
Đấu nối vào quy trình n8n hoặc Zapier để khống chế các hành động nhạy cảm về thời gian — bỏ qua việc gửi email hay báo cáo vào các ngày lễ quốc gia.
Lựa chọn thay thế HolidayAPI & Nager.Date
Dữ liệu năm hiện tại, lập kế hoạch cho năm tương lai và SLA cho production — mà không bị khóa năm ở gói miễn phí hay rủi ro độ tin cậy của dự án cộng đồng.
HolidayAPI | Nager.Date | API Pick ✓ | |
|---|---|---|---|
| Gói miễn phí | Chỉ năm trước | Miễn phí (không SLA) | 100 credit khi đăng ký |
| Dữ liệu năm hiện tại | Chỉ gói trả phí | ✓ | ✓ |
| Dữ liệu năm tương lai | Chỉ gói trả phí | ✓ (giới hạn) | ✓ tới +10 năm |
| Dữ liệu lịch sử (từ 1900) | Chỉ gói trả phí | Một phần | ✓ từ năm 1900 |
| SLA cho production | Chỉ gói trả phí | ✗ Dự án cộng đồng | ✓ |
| Số quốc gia được bao phủ | ~100 | ~110 | 100+ |
| Không cần thẻ tín dụng để bắt đầu | ✗ | ✓ | ✓ |
| Credit / request hết hạn? | Gói hằng năm | N/A | Không bao giờ hết hạn |
| Sẵn sàng cho AI agent / LLM | Một phần | Một phần | ✓ JSON gốc |
Cái bẫy gói miễn phí của HolidayAPI
Gói miễn phí của HolidayAPI cố tình bị giới hạn ở chỉ năm dương lịch trước đó. Cần tra cứu ngày lễ cho năm hiện tại hoặc lên kế hoạch trước cho lịch nghỉ năm 2027? Bạn buộc phải nâng cấp lên gói trả phí. Với bất kỳ trường hợp lập lịch hay tự động hóa nào, điều này khiến gói miễn phí gần như vô dụng ngay từ ngày đầu tiên.
Rủi ro độ tin cậy của Nager.Date
Nager.Date là một dự án mã nguồn mở do cộng đồng duy trì — miễn phí để dùng nhưng không có SLA về thời gian hoạt động, không hợp đồng hỗ trợ và không đảm bảo tiếp tục khả dụng. Những nhóm đã xây dựng hệ thống trả lương hay pipeline logistics trên nó đã bị mắc kẹt bởi sự cố ngừng hoạt động hoặc ngừng phát hành bất ngờ. Ổn cho làm prototype; không ổn cho production.
Các trường phản hồi
| Trường | Kiểu | Mô tả |
|---|---|---|
| data.country | string | Mã quốc gia ISO 3166-1 alpha-2 (chữ hoa) |
| data.country_name | string | Tên đầy đủ tiếng Anh của quốc gia |
| data.year | integer | Năm dương lịch đã truy vấn |
| data.total | integer | Số ngày lễ công cộng trong năm |
| data.holidays | array | Danh sách các object ngày lễ được sắp xếp theo ngày |
| data.holidays[].date | string | Ngày lễ theo định dạng YYYY-MM-DD |
| data.holidays[].name | string | Tên chính thức của ngày lễ |
| credits_used | integer | Credit bị trừ cho request này |
| remaining_credits | integer | Credit còn lại trong tài khoản của bạn |
Giới hạn tần suất
Giới hạn tốc độ tính theo từng API key, cửa sổ trượt 60 giây. Vượt giới hạn, bạn nhận được phản hồi 429 sạch sẽ kèm header Retry-After.
120req/min
Theo từng API key, từng endpoint. Cửa sổ trượt 60 giây.
3concurrent
Số request đang chạy tối đa đồng thời cho mỗi API key.
X-RateLimit-LimitSố request tối đa cho phép mỗi phútX-RateLimit-RemainingSố request còn lại trong cửa sổ hiện tạiX-RateLimit-ResetSố giây cho đến khi cửa sổ hiện tại được đặt lạiRetry-AfterSố giây cần chờ trước khi thử lại (chỉ khi 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
}Câu hỏi thường gặp
Hỏi: Những quốc gia nào được hỗ trợ?
Đáp: Hơn 100 quốc gia thông qua thư viện mã nguồn mở python-holidays (vacanza). Bao gồm Mỹ, Anh, Đức, Pháp, Nhật Bản, Trung Quốc, Úc, Canada, Ấn Độ, Brazil, và hầu hết châu Âu, châu Á, Mỹ Latinh và châu Phi. Dùng một mã ISO 3166-1 alpha-2 hợp lệ (ví dụ US, GB, DE).
Hỏi: Tôi có thể truy vấn ngược và xuôi bao xa?
Đáp: Bạn có thể truy vấn bất kỳ năm nào từ 1900 đến 10 năm trong tương lai. Ngày lễ lịch sử được tính dựa trên các quy tắc có hiệu lực vào thời điểm đó, nên kết quả phản ánh các ngày kỷ niệm lịch sử thực tế chứ không phải quy tắc hiện nay chiếu ngược về quá khứ.
Hỏi: Ngày lễ theo vùng/bang có được bao gồm không?
Đáp: Endpoint này chỉ trả về ngày lễ công cộng cấp quốc gia. Các ngày kỷ niệm theo bang, tỉnh hoặc vùng cụ thể (ví dụ ngày lễ theo bang ở Mỹ, ngày lễ theo Länder ở Đức) không được bao gồm trong phản hồi mặc định. Hãy liên hệ với chúng tôi nếu bạn cần dữ liệu ngày lễ cấp phân vùng.
Hỏi: AI agent có thể dùng cái này làm tool không?
Đáp: Có. Endpoint nhận hai tham số truy vấn (country và year) và trả về một mảng JSON có cấu trúc — đơn giản để định nghĩa làm hàm tool cho OpenAI, Claude, LangChain hay bất kỳ framework agent nào. Lý tưởng cho các agent lập lịch cần suy luận về ngày làm việc trên nhiều quốc gia.
Dùng Public Holidays trong Claude Code & AI Agent
Cài đặt skill Claude Code chính thức để truy vấn ngày lễ công cộng cho hơn 100 quốc gia ngay trong agent code AI của bạn — ngày được sắp xếp, tên chính thức và số lượng qua ngôn ngữ tự nhiên.
Hỏi AI agent của bạn một cách tự nhiên
Nền tảng tương thích
Skill Claude Code cho API Public Holidays của APIpick
Trả về danh sách ngày lễ được sắp xếp theo ngày với tên chính thức tiếng Anh và tổng số lượng cho hơn 100 quốc gia. Hỗ trợ các năm từ 1900 đến 10 năm tới.