Ngày lễ các nước API

Ngày nghỉ lễ, ngày lễ ngân hàng và ngày kỷ niệm của khoảng 200 quốc gia và bang, ngày lễ sắp tới, kiểm tra ngày lễ và đếm ngày làm việc.

GEThttps://apibox.io.vn/v1/holidays
Tiện ích lập trình▶ Dùng thử online

Truyền country (mã ISO, có thể kèm cấp bang/vùng: US-CA, DE-BY, GB-SCT) để nhận các ngày lễ trong year: ngày, ngày kết thúc với lễ kéo dài nhiều ngày, thời điểm bắt đầu và kết thúc theo múi giờ nước đó, tên bản địa, tên tiếng Anh, tên tiếng Việt khi dữ liệu có, loại (public, bank, school, optional, observance) và có phải ngày nghỉ bù hay không. Lọc bằng types=public, chọn ngôn ngữ tên với lang, xem danh sách bang bằng list=states; không truyền country thì API liệt kê mọi quốc gia được hỗ trợ.

Các chế độ khác: date=2026-12-25 cho biết một ngày là ngày lễ, cuối tuần hay ngày làm việc; next=5 trả về các ngày lễ sắp tới tính từ hôm nay (hoặc from); from + to đếm ngày làm việc (tính cả hai đầu) và liệt kê ngày lễ trong khoảng; add=10 + from cộng thêm số ngày làm việc. Cuối tuần theo CLDR của từng nước (thứ Sáu–thứ Bảy ở Ả Rập Xê Út, chỉ Chủ nhật ở Ấn Độ…) hoặc tự đặt weekend=6,0; ngày nghỉ là ngày lễ loại public và bank (đổi bằng business_types), lễ nửa ngày như chiều Đêm Giáng Sinh không tính là ngày nghỉ.

Quy tắc lấy từ dự án mở date-holidays (giấy phép CC BY-SA 4.0, mọi phản hồi đều kèm ghi công), gồm cả lịch Phục sinh, âm lịch, lịch Do Thái và lịch Hồi giáo, được cập nhật hằng tuần. Ngày theo lịch Hồi giáo là ngày tính toán, có thể lệch một ngày so với quan sát trăng thực tế. Với Việt Nam hãy dùng /v1/vn-holidays, theo Bộ luật Lao động và lịch nghỉ chính thức hằng năm.

Tham số

TênVị tríKiểuBắt buộcMặc định
countryquery|pathstringkhôngMã ISO 3166, có thể kèm cấp dưới (US, US-CA, DE-BY). Bỏ trống để liệt kê các nước.
yearquerynumberkhôngNăm (1900–2200, mặc định năm hiện tại).
langquerystringkhôngNgôn ngữ của name (en, vi, de…; mặc định ngôn ngữ của nước đó).
typesquerystringkhôngDanh sách public, bank, school, optional, observance (mặc định: tất cả).
datequerystringkhôngKiểm tra một ngày (YYYY-MM-DD).
nextquerynumberkhôngTrả về N ngày lễ sắp tới (1–100) tính từ hôm nay hoặc from.
fromquerystringkhôngNgày bắt đầu (dùng với to, add hoặc next).
toquerystringkhôngNgày kết thúc: đếm ngày làm việc từ from đến to (tối đa 10 năm).
addquerynumberkhôngCộng N ngày làm việc vào from (số âm để lùi lại).
weekendquerystringkhôngCác ngày cuối tuần, 0 = Chủ nhật … 6 = thứ Bảy (mặc định theo CLDR của nước đó).
business_typesquerystringkhôngpublic,bankLoại ngày lễ được tính là ngày nghỉ.
listquerystringkhôngstates: liệt kê bang / vùng.

Ví dụ

curl "https://apibox.io.vn/v1/holidays?country=US&next=2&from=2026-11-11" \
  -H "Authorization: Bearer YOUR_API_KEY"

Kết quả trả về

{
  "country": "US",
  "country_name": "United States of America",
  "country_name_vi": "Hoa Kỳ",
  "timezone": "America/New_York",
  "languages": [
    "en-us",
    "en"
  ],
  "weekend_days": [
    "saturday",
    "sunday"
  ],
  "from": "2026-11-11",
  "count": 2,
  "holidays": [
    {
      "date": "2026-11-11",
      "end_date": "2026-11-11",
      "days": 1,
      "start": "2026-11-11T05:00:00.000Z",
      "end": "2026-11-12T05:00:00.000Z",
      "name": "Veterans Day",
      "name_en": "Veterans Day",
      "type": "public",
      "rule": "11-11",
      "days_until": 0
    },
    {
      "date": "2026-11-26",
      "end_date": "2026-11-26",
      "days": 1,
      "start": "2026-11-26T05:00:00.000Z",
      "end": "2026-11-27T05:00:00.000Z",
      "name": "Thanksgiving Day",
      "name_en": "Thanksgiving Day",
      "type": "public",
      "rule": "4th thursday in November",
      "days_until": 15
    }
  ],
  "attribution": "Holiday data: date-holidays by commenthol and contributors (https://github.com/commenthol/date-holidays), licensed CC BY-SA 4.0; data version 2026-11-08"
}

Ứng dụng

  • Tính hạn giao hàng, SLA theo ngày làm việc cho khách nước ngoài
  • Hiển thị ngày lễ của Mỹ, Nhật, Hàn hoặc các nước EU cho khách hàng
  • Lên lịch phát hành, trực hệ thống theo ngày nghỉ của đội ở nước ngoài
  • Chặn đặt lịch vào ngày nghỉ lễ

Hỏi đáp

Dữ liệu lấy từ đâu?

Từ dự án date-holidays (github.com/commenthol/date-holidays), giấy phép CC BY-SA 4.0; cần giữ trường attribution khi công bố lại dữ liệu.

Có ngày lễ riêng của bang, vùng không?

Có, với các nước có dữ liệu cấp dưới: dùng country=US-CA hoặc state=CA; list=states cho biết các mã.

Còn Việt Nam thì sao?

Có dữ liệu Việt Nam, nhưng /v1/vn-holidays chính xác hơn: áp dụng Bộ luật Lao động và lịch nghỉ Tết, 2/9 chính thức.

API liên quan

Bắt đầu với 1.000 request miễn phí mỗi tháng. Nhận API key miễn phí →