World public holidays API

Public, bank and observance holidays of ~200 countries and their states, next holidays, is-it-a-holiday checks and business days between dates.

GEThttps://apibox.io.vn/v1/holidays

Developer utilities▶ Try it online

Give a country (ISO code, optionally with a subdivision: US-CA, DE-BY, GB-SCT) and get its holidays for a year: date, end date for multi-day holidays, start and end instants in the country time zone, local name, English name, Vietnamese name when the data has one, type (public, bank, school, optional, observance) and whether it is a substitute day. Filter with types=public, choose the name language with lang, and list subdivisions with list=states; without country the API lists every supported country.

Other modes: date=2026-12-25 tells whether a day is a holiday, a weekend or a business day; next=5 returns the next holidays from today (or from); from + to counts business days (both dates included) and lists the holidays in the range; add=10 + from adds business days. Weekends follow CLDR per country (Friday–Saturday in Saudi Arabia, Sunday only in India…) or weekend=6,0; days off are holidays of type public and bank (business_types to change), half-day holidays such as Christmas Eve afternoon do not close the day.

Rules come from the open date-holidays project (CC BY-SA 4.0, attribution returned in every response), including Easter, lunar, Hebrew and Islamic calendars, and are refreshed weekly. Islamic dates are calculated and may differ by a day from moon sightings. For Vietnam use /v1/vn-holidays, which follows the Labour Code and the official yearly schedules.

Parameters

Name	In	Type	Required	Default
`country`	query\|path	string	no		ISO 3166 code, optionally with subdivision (`US`, `US-CA`, `DE-BY`). Omit to list countries.
`year`	query	number	no		Year (1900–2200, default: current year).
`lang`	query	string	no		Language of `name` (`en`, `vi`, `de`, …; default: the country language).
`types`	query	string	no		Comma list of `public`, `bank`, `school`, `optional`, `observance` (default: all).
`date`	query	string	no		Check one day (YYYY-MM-DD).
`next`	query	number	no		Return the next N holidays (1–100) from today or `from`.
`from`	query	string	no		Start date (with `to`, `add` or `next`).
`to`	query	string	no		End date: count business days from `from` to `to` (max 10 years).
`add`	query	number	no		Add N business days to `from` (negative to go back).
`weekend`	query	string	no		Weekend days, 0 = Sunday … 6 = Saturday (default: CLDR for the country).
`business_types`	query	string	no	`public,bank`	Holiday types that close business days.
`list`	query	string	no		`states`: list subdivisions and regions.

Example

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

const res = await fetch('https://apibox.io.vn/v1/holidays?country=US&next=2&from=2026-11-11', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/holidays?country=US&next=2&from=2026-11-11",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/holidays?country=US&next=2&from=2026-11-11');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "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"
}

Use cases

Compute delivery or SLA deadlines in business days for foreign clients
Show customers holidays of the US, Japan, Korea or EU countries
Plan releases and on-call around team holidays abroad
Block booking dates on public holidays

FAQ

Where does the data come from?

From the date-holidays project (github.com/commenthol/date-holidays), licensed CC BY-SA 4.0; the attribution field must be kept when you republish the data.

Are state or regional holidays included?

Yes, for countries with subdivisions in the data: use country=US-CA or state=CA; list=states shows the codes.

What about Vietnam?

Vietnam is included, but /v1/vn-holidays is more accurate: it applies the Labour Code and the official Tết and 2/9 schedules.

World public holidays API

Parameters

Example

Response

Use cases

FAQ

Related APIs

UUID Generator

Cron Expression Parser

Time & Timezone Converter