Skip to main content

Public Holidays API

REAL DATA

Real public holidays for 61 countries, computed from official national rules — list a year, check a date, or get the next upcoming holiday.

Authoritative reference data or standards computation

Base URL
/api/holidays
Category
Date & Time
Capabilities
4 routes
Last updated
July 29, 2026
Data sources · 3

GET /api/holidays All holidays of a country for a given year

Live requestRuns against the public API
No key required
GET/api/holidays?country=DK&year=2026

Request parameters

Country code (ISO 3166-1 alpha-2). 61 supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA — unsupported codes return a 400 listing all options, never another country's holidays. `GET /api/holidays/countries` returns each country's scope, coverage and official source.

Calendar year. Defaults to the current year.

Filter by holiday type: 'public' = statutory day off, 'bank' = banks closed, 'observance' = widely kept but not statutory.

Advanced response options6 options

Limit the number of returned records (1–100). Defaults to all matches.

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/holidays?country=DK&year=2026"
const res = await fetch("https://randomapi.dev/api/holidays?country=DK&year=2026");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/holidays?country=DK&year=2026").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/holidays?country=DK&year=2026"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 3
country string required

Country code (ISO 3166-1 alpha-2). 61 supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA — unsupported codes return a 400 listing all options, never another country's holidays. `GET /api/holidays/countries` returns each country's scope, coverage and official source.

example: country=DK
year int

Calendar year. Defaults to the current year.

allowed: 1583 – 3000
example: year=2026
type enum

Filter by holiday type: 'public' = statutory day off, 'bank' = banks closed, 'observance' = widely kept but not statutory.

default: any
allowed: public | bank | observance | any
example: type=public
Universal parameters Shared response and formatting options 6
count int

Limit the number of returned records (1–100). Defaults to all matches.

default: all matches
allowed: 1 – 100
example: count=3
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=date,name
exclude list

Return all fields except these (comma-separated).

example: exclude=observed
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 6
date string (YYYY-MM-DD)

The holiday's actual date.

example: 2026-12-25

name string

English name.

example: Christmas Day

localName string

Name in the country's main language.

example: Juledag

type string

public | bank | observance.

example: public

weekday string

Weekday of the actual date.

example: Friday

observed string (YYYY-MM-DD) nullable

Substitute/observed date when the holiday is shifted off a weekend, else null.

example: null

Documented examples

Build-generated requests and complete responses 4
Danish holidays in 2026
GET /api/holidays?country=DK&year=2026 
{
  "data": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "localName": "Nytårsdag",
      "type": "public",
      "weekday": "Thursday",
      "observed": null
    },
    {
      "date": "2026-04-02",
      "name": "Maundy Thursday",
      "localName": "Skærtorsdag",
      "type": "public",
      "weekday": "Thursday",
      "observed": null
    },
    {
      "date": "2026-04-03",
      "name": "Good Friday",
      "localName": "Langfredag",
      "type": "public",
      "weekday": "Friday",
      "observed": null
    },
    {
      "date": "2026-04-05",
      "name": "Easter Sunday",
      "localName": "Påskedag",
      "type": "public",
      "weekday": "Sunday",
      "observed": null
    },
    {
      "date": "2026-04-06",
      "name": "Easter Monday",
      "localName": "2. påskedag",
      "type": "public",
      "weekday": "Monday",
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
US federal holidays this year
GET /api/holidays?country=US 
{
  "data": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "localName": "New Year's Day",
      "type": "public",
      "weekday": "Thursday",
      "observed": null
    },
    {
      "date": "2026-01-19",
      "name": "Martin Luther King Jr. Day",
      "localName": "Martin Luther King Jr. Day",
      "type": "public",
      "weekday": "Monday",
      "observed": null
    },
    {
      "date": "2026-02-16",
      "name": "Washington's Birthday",
      "localName": "Washington's Birthday (Presidents' Day)",
      "type": "public",
      "weekday": "Monday",
      "observed": null
    },
    {
      "date": "2026-05-25",
      "name": "Memorial Day",
      "localName": "Memorial Day",
      "type": "public",
      "weekday": "Monday",
      "observed": null
    },
    {
      "date": "2026-06-19",
      "name": "Juneteenth National Independence Day",
      "localName": "Juneteenth",
      "type": "public",
      "weekday": "Friday",
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Japan 2026 (equinox + Citizens' Holiday)
GET /api/holidays?country=JP&year=2026 
{
  "data": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "localName": "元日",
      "type": "public",
      "weekday": "Thursday",
      "observed": null
    },
    {
      "date": "2026-01-12",
      "name": "Coming of Age Day",
      "localName": "成人の日",
      "type": "public",
      "weekday": "Monday",
      "observed": null
    },
    {
      "date": "2026-02-11",
      "name": "National Foundation Day",
      "localName": "建国記念の日",
      "type": "public",
      "weekday": "Wednesday",
      "observed": null
    },
    {
      "date": "2026-02-23",
      "name": "Emperor's Birthday",
      "localName": "天皇誕生日",
      "type": "public",
      "weekday": "Monday",
      "observed": null
    },
    {
      "date": "2026-03-20",
      "name": "Vernal Equinox Day",
      "localName": "春分の日",
      "type": "public",
      "weekday": "Friday",
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Only statutory days off
GET /api/holidays?country=SE&year=2026&type=public 
{
  "data": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "localName": "Nyårsdagen",
      "type": "public",
      "weekday": "Thursday",
      "observed": null
    },
    {
      "date": "2026-01-06",
      "name": "Epiphany",
      "localName": "Trettondedag jul",
      "type": "public",
      "weekday": "Tuesday",
      "observed": null
    },
    {
      "date": "2026-04-03",
      "name": "Good Friday",
      "localName": "Långfredagen",
      "type": "public",
      "weekday": "Friday",
      "observed": null
    },
    {
      "date": "2026-04-05",
      "name": "Easter Sunday",
      "localName": "Påskdagen",
      "type": "public",
      "weekday": "Sunday",
      "observed": null
    },
    {
      "date": "2026-04-06",
      "name": "Easter Monday",
      "localName": "Annandag påsk",
      "type": "public",
      "weekday": "Monday",
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}

GET /api/holidays/check Is a given date (default: today) a holiday?

Defaults to today in the country's primary timezone, so a bare ?country=DK answers “is today a holiday in Denmark?”. Observed/substitute days match too.

Live requestRuns against the public API
No key required
GET/api/holidays/check?country=DK

Request parameters

Country code (ISO 3166-1 alpha-2). 61 supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA — unsupported codes return a 400 listing all options, never another country's holidays. `GET /api/holidays/countries` returns each country's scope, coverage and official source.

Date to check (YYYY-MM-DD). Defaults to today in the country's timezone.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/holidays/check?country=DK"
const res = await fetch("https://randomapi.dev/api/holidays/check?country=DK");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/holidays/check?country=DK").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/holidays/check?country=DK"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 2
country string required

Country code (ISO 3166-1 alpha-2). 61 supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA — unsupported codes return a 400 listing all options, never another country's holidays. `GET /api/holidays/countries` returns each country's scope, coverage and official source.

example: country=DK
date date

Date to check (YYYY-MM-DD). Defaults to today in the country's timezone.

example: date=2026-12-25
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=country,countryName
exclude list

Return all fields except these (comma-separated).

example: exclude=holiday
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 8
country string

ISO 3166-1 alpha-2 code.

example: DK

countryName string

English country name.

example: Denmark

date string (YYYY-MM-DD)

The date that was checked.

example: 2026-12-25

weekday string

Weekday of that date.

example: Friday

isPublicHoliday boolean

True when the date is a statutory public holiday (or its observed substitute).

example: true

isWeekend boolean

True when the date is one of the country's weekly rest days (Saturday/Sunday in every country currently supported).

example: false

coverage string

'complete' when every nationwide holiday is computed, 'partial' when some are deliberately excluded (see meta.warnings).

example: complete

holiday object nullable

The matching holiday (any type), incl. its type and observed date — null when none.

example: {"date":"2026-12-25","name":"Christmas Day","localName":"Juledag","type":"public","weekday":"Friday","observed":null}

Documented examples

Build-generated requests and complete responses 4
Is today a holiday in Denmark?
GET /api/holidays/check?country=DK 
{
  "data": {
    "country": "DK",
    "countryName": "Denmark",
    "date": "2026-07-29",
    "weekday": "Wednesday",
    "isPublicHoliday": false,
    "isWeekend": false,
    "coverage": "complete",
    "holiday": null
  },
  "meta": {
    "endpoint": "holidays",
    "route": "/check",
    "params": {
      "country": "DK",
      "date": "2026-07-29"
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Check Christmas 2026 in Germany
GET /api/holidays/check?country=DE&date=2026-12-25 
{
  "data": {
    "country": "DE",
    "countryName": "Germany",
    "date": "2026-12-25",
    "weekday": "Friday",
    "isPublicHoliday": true,
    "isWeekend": false,
    "coverage": "complete",
    "holiday": {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "localName": "Erster Weihnachtstag",
      "type": "public",
      "weekday": "Friday",
      "observed": null
    }
  },
  "meta": {
    "endpoint": "holidays",
    "route": "/check",
    "params": {
      "country": "DE",
      "date": "2026-12-25"
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
South Africa's Monday after Women's Day
GET /api/holidays/check?country=ZA&date=2026-08-10 
{
  "data": {
    "country": "ZA",
    "countryName": "South Africa",
    "date": "2026-08-10",
    "weekday": "Monday",
    "isPublicHoliday": true,
    "isWeekend": false,
    "coverage": "complete",
    "holiday": {
      "date": "2026-08-09",
      "name": "National Women's Day",
      "localName": "National Women's Day",
      "type": "public",
      "weekday": "Sunday",
      "observed": "2026-08-10"
    }
  },
  "meta": {
    "endpoint": "holidays",
    "route": "/check",
    "params": {
      "country": "ZA",
      "date": "2026-08-10"
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
US observed day (July 3, 2026)
GET /api/holidays/check?country=US&date=2026-07-03 
{
  "data": {
    "country": "US",
    "countryName": "United States",
    "date": "2026-07-03",
    "weekday": "Friday",
    "isPublicHoliday": true,
    "isWeekend": false,
    "coverage": "complete",
    "holiday": {
      "date": "2026-07-04",
      "name": "Independence Day",
      "localName": "Independence Day",
      "type": "public",
      "weekday": "Saturday",
      "observed": "2026-07-03"
    }
  },
  "meta": {
    "endpoint": "holidays",
    "route": "/check",
    "params": {
      "country": "US",
      "date": "2026-07-03"
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}

GET /api/holidays/next The next upcoming holiday(s)

Returns upcoming holidays from a start date (default: today in the country's timezone), nearest first. count controls how many (default 1).

Live requestRuns against the public API
No key required
GET/api/holidays/next?country=DK

Request parameters

Country code (ISO 3166-1 alpha-2). 61 supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA — unsupported codes return a 400 listing all options, never another country's holidays. `GET /api/holidays/countries` returns each country's scope, coverage and official source.

Start date (exclusive of past, inclusive of today). Defaults to today in the country's timezone.

Filter by holiday type: 'public' = statutory day off, 'bank' = banks closed, 'observance' = widely kept but not statutory.

Advanced response options6 options

Limit the number of returned records (1–100). Defaults to 1.

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/holidays/next?country=DK"
const res = await fetch("https://randomapi.dev/api/holidays/next?country=DK");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/holidays/next?country=DK").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/holidays/next?country=DK"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 3
country string required

Country code (ISO 3166-1 alpha-2). 61 supported: AM, AR, AT, AU, BE, BG, BO, BR, BY, CA, CH, CO, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, GT, HR, HU, IE, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MA, MT, MX, NG, NL, NO, NZ, PA, PE, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM, TH, TR, UA, US, ZA — unsupported codes return a 400 listing all options, never another country's holidays. `GET /api/holidays/countries` returns each country's scope, coverage and official source.

example: country=DK
from date

Start date (exclusive of past, inclusive of today). Defaults to today in the country's timezone.

example: from=2026-06-11
type enum

Filter by holiday type: 'public' = statutory day off, 'bank' = banks closed, 'observance' = widely kept but not statutory.

default: public
allowed: public | bank | observance | any
example: type=public
Universal parameters Shared response and formatting options 6
count int

Limit the number of returned records (1–100). Defaults to 1.

default: 1
allowed: 1 – 100
example: count=3
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=date,name
exclude list

Return all fields except these (comma-separated).

example: exclude=daysUntil
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 7
date string (YYYY-MM-DD)

The holiday's date.

example: 2026-12-25

name string

English name.

example: Christmas Day

localName string

Local name.

example: Juledag

type string

public | bank | observance.

example: public

weekday string

Weekday of the date.

example: Friday

observed string (YYYY-MM-DD) nullable

Observed date when shifted, else null.

example: null

daysUntil integer

Whole days from the start date.

example: 197

Documented examples

Build-generated requests and complete responses 4
Next public holiday in Denmark
GET /api/holidays/next?country=DK 
{
  "data": [
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "localName": "Juledag",
      "type": "public",
      "weekday": "Friday",
      "observed": null,
      "daysUntil": 149
    }
  ],
  "meta": {
    "endpoint": "holidays",
    "route": "/next",
    "count": 1,
    "params": {
      "country": "DK",
      "type": "public",
      "from": "2026-07-29"
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Next 3 from a fixed date
GET /api/holidays/next?country=GB&from=2026-06-11&count=3 
{
  "data": [
    {
      "date": "2026-08-31",
      "name": "Summer Bank Holiday",
      "localName": "Summer Bank Holiday",
      "type": "public",
      "weekday": "Monday",
      "observed": null,
      "daysUntil": 81
    },
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "localName": "Christmas Day",
      "type": "public",
      "weekday": "Friday",
      "observed": null,
      "daysUntil": 197
    },
    {
      "date": "2026-12-26",
      "name": "Boxing Day",
      "localName": "Boxing Day",
      "type": "public",
      "weekday": "Saturday",
      "observed": "2026-12-28",
      "daysUntil": 198
    }
  ],
  "meta": {
    "endpoint": "holidays",
    "route": "/next",
    "count": 3,
    "params": {
      "country": "GB",
      "from": "2026-06-11",
      "type": "public"
    },
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Next 5 in Japan
GET /api/holidays/next?country=JP&from=2026-04-01&count=5 
{
  "data": [
    {
      "date": "2026-04-29",
      "name": "Shōwa Day",
      "localName": "昭和の日",
      "type": "public",
      "weekday": "Wednesday",
      "observed": null,
      "daysUntil": 28
    },
    {
      "date": "2026-05-03",
      "name": "Constitution Memorial Day",
      "localName": "憲法記念日",
      "type": "public",
      "weekday": "Sunday",
      "observed": "2026-05-06",
      "daysUntil": 32
    },
    {
      "date": "2026-05-04",
      "name": "Greenery Day",
      "localName": "みどりの日",
      "type": "public",
      "weekday": "Monday",
      "observed": null,
      "daysUntil": 33
    },
    {
      "date": "2026-05-05",
      "name": "Children's Day",
      "localName": "こどもの日",
      "type": "public",
      "weekday": "Tuesday",
      "observed": null,
      "daysUntil": 34
    },
    {
      "date": "2026-07-20",
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Include bank days & observances
GET /api/holidays/next?country=DK&type=any&count=5 
{
  "data": [
    {
      "date": "2026-12-24",
      "name": "Christmas Eve",
      "localName": "Juleaftensdag",
      "type": "bank",
      "weekday": "Thursday",
      "observed": null,
      "daysUntil": 148
    },
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "localName": "Juledag",
      "type": "public",
      "weekday": "Friday",
      "observed": null,
      "daysUntil": 149
    },
    {
      "date": "2026-12-26",
      "name": "Second Day of Christmas",
      "localName": "2. juledag",
      "type": "public",
      "weekday": "Saturday",
      "observed": null,
      "daysUntil": 150
    },
    {
      "date": "2026-12-31",
      "name": "New Year's Eve",
      "localName": "Nytårsaftensdag",
      "type": "observance",
      "weekday": "Thursday",
      "observed": null,
      "daysUntil": 155
    },
    {
      "date": "2027-01-01",
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}

GET /api/holidays/countries Every supported country with its scope, coverage and official source

The auditable index of the holiday engine: what each country's ruleset covers, whether that coverage is complete or a documented subset, and the government source every rule was verified against.

Live requestRuns against the public API
No key required
GET/api/holidays/countries?count=100

Request parameters

Filter by coverage: 'complete' = every nationwide public holiday is computed; 'partial' = some are deliberately excluded and named in coverageNote.

Advanced response options6 options

Limit the number of returned records (1–100). Defaults to all matches.

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/holidays/countries?count=100"
const res = await fetch("https://randomapi.dev/api/holidays/countries?count=100");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/holidays/countries?count=100").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/holidays/countries?count=100"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 1
coverage enum

Filter by coverage: 'complete' = every nationwide public holiday is computed; 'partial' = some are deliberately excluded and named in coverageNote.

default: any
allowed: any | complete | partial
example: coverage=partial
Universal parameters Shared response and formatting options 6
count int

Limit the number of returned records (1–100). Defaults to all matches.

default: all matches
allowed: 1 – 100
example: count=3
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=country,countryName
exclude list

Return all fields except these (comma-separated).

example: exclude=sources
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 12
country string

ISO 3166-1 alpha-2 code.

example: JP

countryName string

English country name.

example: Japan

timezone string

IANA timezone used to resolve 'today' for this country.

example: Asia/Tokyo

coverage string

'complete' or 'partial'.

example: complete

coverageNote string nullable

For partial calendars: exactly which holidays are excluded and why. Null when nothing is excluded.

example: null

scope string

What level of holiday the ruleset covers (federal, nationwide, bank holidays…).

example: The national holidays (国民の祝日) of the Act on National Holidays…

weekend string[]

The country's weekly rest days.

example: ["Saturday","Sunday"]

holidayRules integer

Number of rules in the ruleset (more than the holidays in any one year, because superseded and future rules are kept).

example: 29

verifiedFrom integer nullable

First year the ruleset is verified for; null when no extra bound beyond the endpoint's range.

example: 1988

verifiedTo integer nullable

Last year the ruleset is verified for; null when unbounded.

example: 2099

rulesVerified string (YYYY-MM-DD)

Date the whole rule set was last re-checked against its cited sources.

example: 2026-07-29

sources object[]

Official statute/ministry page(s) the rules were verified against.

example: [{"label":"Cabinet Office of Japan — 国民の祝日について","url":"https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html"}]

Documented examples

Build-generated requests and complete responses 3
Every supported country
GET /api/holidays/countries?count=100 
{
  "data": [
    {
      "country": "AM",
      "countryName": "Armenia",
      "timezone": "Asia/Yerevan",
      "coverage": "complete",
      "coverageNote": "The Government occasionally declares extra non-working days between 1 and 6 January by separate decision; those one-off additions are not modelled.",
      "scope": "Non-working holidays under Labour Code art. 160. Every Armenian public holiday is a fixed Gregorian date — the Armenian Apostolic Church keeps Christmas and Epiphany together on 6 January, so no Easter rule is involved.",
      "weekend": [
        "Sunday",
        "Saturday"
      ],
      "holidayRules": 12,
      "verifiedFrom": 2020,
      "verifiedTo": null,
      "rulesVerified": "2026-07-29",
      "sources": [
        {
          "label": "Government of Armenia — public holidays and commemoration days",
          "url": "https://www.gov.am/en/holidays/"
        }
      ]
    },
    {
      "country": "AR",
      "countryName": "Argentina",
      "timezone": "America/Argentina/Buenos_Aires",
      "coverage": "complete",
      "coverageNote": "Two Argentine mechanisms are deliberately NOT computed because they are discretionary, not algorithmic: the up-to-three 'días no laborables con fines turísticos' the executive decrees each year, and Decreto 614/2025, which lets the Jefatura de Gabinete move a trasladable that lands on a Saturday or Sunday to the adjacent Friday or Monday. Religious days for Jewish and Muslim workers are personal entitlements, not general holidays, and are excluded.",
      "scope": "National holidays under Ley 27.399: the twelve feriados inamovibles plus the four feriados trasladables, whose statutory move (Tue/Wed → preceding Monday, Thu/Fri → following Monday) is computed.",
      "weekend": [
        "Sunday",
        "Saturday"
      ],
      "holidayRules": 16,
      "verifiedFrom": 2018,
      "verifiedTo": null,
      "rulesVerified": "2026-07-29",
      "sources": [
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Only fully computed calendars
GET /api/holidays/countries?coverage=complete 
{
  "data": [
    {
      "country": "AM",
      "countryName": "Armenia",
      "timezone": "Asia/Yerevan",
      "coverage": "complete",
      "coverageNote": "The Government occasionally declares extra non-working days between 1 and 6 January by separate decision; those one-off additions are not modelled.",
      "scope": "Non-working holidays under Labour Code art. 160. Every Armenian public holiday is a fixed Gregorian date — the Armenian Apostolic Church keeps Christmas and Epiphany together on 6 January, so no Easter rule is involved.",
      "weekend": [
        "Sunday",
        "Saturday"
      ],
      "holidayRules": 12,
      "verifiedFrom": 2020,
      "verifiedTo": null,
      "rulesVerified": "2026-07-29",
      "sources": [
        {
          "label": "Government of Armenia — public holidays and commemoration days",
          "url": "https://www.gov.am/en/holidays/"
        }
      ]
    },
    {
      "country": "AR",
      "countryName": "Argentina",
      "timezone": "America/Argentina/Buenos_Aires",
      "coverage": "complete",
      "coverageNote": "Two Argentine mechanisms are deliberately NOT computed because they are discretionary, not algorithmic: the up-to-three 'días no laborables con fines turísticos' the executive decrees each year, and Decreto 614/2025, which lets the Jefatura de Gabinete move a trasladable that lands on a Saturday or Sunday to the adjacent Friday or Monday. Religious days for Jewish and Muslim workers are personal entitlements, not general holidays, and are excluded.",
      "scope": "National holidays under Ley 27.399: the twelve feriados inamovibles plus the four feriados trasladables, whose statutory move (Tue/Wed → preceding Monday, Thu/Fri → following Monday) is computed.",
      "weekend": [
        "Sunday",
        "Saturday"
      ],
      "holidayRules": 16,
      "verifiedFrom": 2018,
      "verifiedTo": null,
      "rulesVerified": "2026-07-29",
      "sources": [
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}
Partial calendars and what they exclude
GET /api/holidays/countries?coverage=partial 
{
  "data": [
    {
      "country": "IN",
      "countryName": "India",
      "timezone": "Asia/Kolkata",
      "coverage": "partial",
      "coverageNote": "Only the three nationally uniform holidays are computed. The Department of Personnel & Training's gazetted list (17 days in 2026) additionally contains Holi, Diwali, Eid, Guru Nanak Jayanti and similar festivals whose dates come from lunar/lunisolar/Hijri calendars and are notified annually — those are NOT included, and neither are any state holidays.",
      "scope": "The three holidays that are uniform across all of India — Republic Day, Independence Day and Gandhi Jayanti. Every other Indian holiday is either a state holiday or a 'gazetted/restricted' holiday whose date depends on lunar, lunisolar or Hijri calendars.",
      "weekend": [
        "Sunday",
        "Saturday"
      ],
      "holidayRules": 3,
      "verifiedFrom": 2020,
      "verifiedTo": null,
      "rulesVerified": "2026-07-29",
      "sources": [
        {
          "label": "National Portal of India — holiday calendar",
          "url": "https://www.india.gov.in/calendar"
        }
      ]
    },
    {
      "country": "KE",
      "countryName": "Kenya",
      "timezone": "Africa/Nairobi",
      "coverage": "partial",
      "coverageNote": "Idd-ul-Fitr and Idd-ul-Azha are gazetted Kenyan public holidays but follow the Hijri calendar and are declared per year, so they are NOT computed here. The President may also gazette additional one-off public holidays.",
      "scope": "Gazetted national public holidays under the Public Holidays Act (Cap. 110), with the Act's rule that a public holiday falling on a Sunday makes the following day a holiday.",
      "weekend": [
        "Sunday",
        "Saturday"
      ],
      "holidayRules": 11,
      "verifiedFrom": 2021,
      "verifiedTo": null,
      "rulesVerified": "2026-07-29",
      "sources": [
    …
    "generatedAt": "2026-07-29T08:14:02.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Holiday dates are computed from each country's official rules — fixed dates, Gregorian Computus (Western Easter), the Orthodox Paschalion, nth-weekday rules, statutory Monday moves and observed-day shifts — including abolitions: Denmark's Store bededag correctly disappears from 2024 onward.

Coverage is national-level holidays for 61 countries across Europe, the Americas, Asia-Pacific and Africa. Every ruleset cites the official statute or ministry page it was verified against, and GET /api/holidays/countries returns those citations along with each country's scope.

Honest partial calendars. 10 countries (IN, KE, KR, KZ, MA, NG, PH, SG, TH, TR) have holidays that follow lunar or Hijri calendars, or that a government announces per year. Those dates are not guessed — they are left out, the country is flagged coverage: "partial", and every response for it carries a warning naming exactly which holidays are missing. An honest partial calendar beats a silently wrong one.

Four routes answer the four real questions:

  • /api/holidays — every holiday of a given year.
  • /api/holidays/check — "is this date (default: today) a holiday?"
  • /api/holidays/next — "when is the next one?"
  • /api/holidays/countries — "which countries are supported, how complete is each, and where do the rules come from?"

Weekend-shifted "observed" days (US federal style, UK/Kenya/South Africa substitute days, Japan's 振替休日) are included via the observed field, and /check also matches observed dates. Rules last re-verified 2026-07-29.

Use it for

  • Disable delivery/booking dates that fall on public holidays
  • Show an 'is today a holiday?' banner without maintaining your own table
  • Compute business days and SLA deadlines around national holidays
  • Audit which national calendars a scheduling feature can safely support

Frequently asked questions

Practical answers about this endpoint 6
How do I check if a date is a public holiday?

/api/holidays/check?country=US&date=2026-07-04 answers directly with the verdict and the holiday's details; omit date and it checks today.

Which countries are supported?

61 countries across Europe, the Americas, Asia-Pacific and Africa. GET /api/holidays/countries lists every one with its scope, its coverage flag and the official government source its rules were verified against.

Are lunar and Islamic holidays included?

Only where a published algorithm or an official fixed date exists. Countries whose calendars depend on lunar/Hijri dates announced per year ship the computable subset, are flagged coverage: "partial", and every response names the excluded holidays in meta.warnings.

Are the dates actually correct?

Every ruleset is checked against the country's own statute or ministry page, cited in /api/holidays/countries. Regression tests pin known dates — Japan's 2026 Citizens' Holiday on 22 September, Colombia's Ley Emiliani Mondays, Orthodox Easter on 12 April 2026 — and a parity script fails if any computed date changes.

What's the difference between public, bank and observance?

type classifies each entry: public are statutory days off, bank are bank-specific or half-day closures, observance are widely marked but not days off. Filter with type=public.

How do I get the next upcoming holiday?

/api/holidays/next?country=DE returns the next holiday from today for that country.

Related APIs

Useful next tools in the catalog
Business Days Calculator API REAL DATA

Add, count or inspect business days using verified national public-holiday rules for 61 countries, including observed substitute days.
Date Info API REAL DATA

Real calendar facts for any date — weekday, ISO week, day of year, quarter, leap year, days in month, weekend flag and Unix timestamp. Defaults to today.
Random Date Generator API MOCK DATA

Uniformly random timestamps from any date range — ISO instant, Unix seconds, date, time and weekday — with an exact weekdays-only mode and seeded results.
Timezone Database API REAL DATA

Live IANA offsets, DST transitions, local-time ambiguity resolution and exact instant conversion — no guessed wall-clock mappings.