What if there are no matches?

A covered period with no holidays returns an empty holidays array. An unpublished year returns 404 with the published range. Invalid dates and conflicting path and query values return 400.

Use /holiday/US/2026 for a year or /holiday/US/2026-12 for a month. Both return holidays arrays. A full date path returns the holiday on that day, or null.

How do I check one date?

GET /holiday/US/2026-12-25 returns the holiday or null. To get every holiday on that date, use /holiday/US?year=2026&month=12&day=25.

GET /holiday/{country} · /{country}/{period}

Holiday API

Choose a country and a year, month, or date.

You have a country and a day. The holiday, or null.

Example response/holiday/US/2026-10-31

{
  "country": "US",
  "date": "2026-10-31",
  
    "date": "2026-10-31",
    "name": "Halloween",
    "name_local": null,
    "type": "observance",
    "regions": null,
    "substitute": false
  }
}

1M requests · $20/mo. Get started

What comes back.

date

Date, YYYY-MM-DD

name

Official name, English or the official translation (France stays French)

type

public for an official day off, observance for cultural days (Halloween, Black Friday)

substitute

The day off moved (a holiday falling on a weekend, observed on a weekday)

regions

Region codes when only part of the country takes the day (GB: ENG, WLS, SCT, NIR), null when nationwide

holiday

The holiday on that date (same shape as holidays[]), or null

holidays

Every matching holiday and observance, including multiple names on one date. Empty array for a covered period with no matches

Pass a country

150 countries and territories. Official published calendars.

Choose a period

A year or month returns every matching holiday in an array.

Check one date

Day filters return all matches. A date path returns the holiday or null.

Coverage

150 countries and territories, from official published calendars.

Aland Islands
Albania
Andorra
Angola
Anguilla
Argentina
Armenia
Aruba
Australia
Austria
Azerbaijan
Bahamas
Bahrain
Bangladesh
Barbados
Belarus
Belgium
Belize
Benin
Bermuda
Bhutan
Bolivia
Bonaire, Saint Eustatius and Saba
Botswana
Brazil
British Virgin Islands
Brunei
Bulgaria
Cambodia
Canada
Cayman Islands
Chile
China
Colombia
Cook Islands
Costa Rica
Croatia
Czechia
Denmark
Dominica
Dominican Republic
East Timor
Ecuador
Egypt
Estonia
Falkland Islands
Fiji
Finland
France
French Guiana
French Polynesia
Georgia
Germany
Ghana
Greece
Guadeloupe
Guam
Guatemala
Hong Kong
Hungary
Iceland
India
Indonesia
Iraq
Ireland
Isle of Man
Italy
Jamaica
Japan
Jersey
Jordan
Kazakhstan
Kenya
Kosovo
Kyrgyzstan
Laos
Latvia
Lebanon
Liechtenstein
Lithuania
Luxembourg
Macao
Malaysia
Malta
Marshall Islands
Martinique
Mauritius
Mayotte
Mexico
Monaco
Mongolia
Montenegro
Namibia
Nauru
Netherlands
New Caledonia
New Zealand
Nigeria
Norfolk Island
North Macedonia
Northern Mariana Islands
Norway
Oman
Panama
Papua New Guinea
Paraguay
Peru
Philippines
Poland
Portugal
Qatar
Republic of the Congo
Reunion
Romania
Russia
Saint Barthelemy
Saint Helena
Saint Lucia
Saint Martin
Saint Pierre and Miquelon
Saint Vincent and the Grenadines
Samoa
San Marino
Saudi Arabia
Serbia
Seychelles
Singapore
Slovakia
Slovenia
Solomon Islands
South Africa
South Korea
Spain
Sri Lanka
Sweden
Taiwan
Thailand
Tonga
Turkey
Turkmenistan
Turks and Caicos Islands
United Arab Emirates
United Kingdom
United States
Uruguay
Uzbekistan
Vanuatu
Venezuela
Vietnam
Zimbabwe

7,089
public holidays: 1,353
observances: 1955
JP calendar since

Pass a country code and get that year's holidays: date, name, type, and whether the observed date moved (substitute). Each calendar follows its official published source. Years carry cultural observances like Halloween, Mother's Day, and White Day next to the official days, told apart by type. Choose a year at /holiday/US/2026 or a month at /holiday/US/2026-12. Query filters year, month, and day return every matching holiday in an array. A full date at /holiday/US/2026-12-25 keeps the holiday or null response. Covered empty periods return an empty array. Unpublished years return 404.

France, Austria, and Slovenia keep their native names. Japan, Hong Kong, and Taiwan pair the English name with the native form in name_local. Regional holidays carry subdivision codes in regions. NZ covers national observed dates; US covers federal holidays. Most newer calendars cover reviewed 2026 editions. Belgium, Denmark and Luxembourg also cover 2027, Lithuania covers 2026-2028, Jersey covers 2025-2027, and Bermuda covers 2026-2029. AU excludes part-days and local exceptions; CA covers provincial and territorial general holidays, excluding employer-selected Easter and substitute dates. China lists statutory festival dates, excluding extended breaks and make-up workdays. Thailand and Vietnam cover government holidays; private employers choose separate calendars. Uruguay includes designated working holidays; Romania uses Orthodox movable dates. Turkey excludes half-day holidays and Saturday extensions. Official holiday status does not always mean time off.

SPEED

How long /holiday takes.

Median time to first byte over the last seven days. Warm requests, measured every 30 minutes. Live verification and other request variants can take longer.

30ms

27ms

APAC

48ms

LatAm

24ms

114ms

See live status →

Make your first request.

One key works across the APIs. Copy a request in your language and get JSON back.

curl "https://api.parseapi.com/holiday/US?year=2026" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0"

// Example response · 200
{
  "country": "US",
  "year": 2026,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-01-19",
      "name": "Birthday of Martin Luther King, Jr.",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-02-14",
      "name": "Valentine's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-02-16",
      "name": "Washington's Birthday",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-03-17",
      "name": "St. Patrick's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-04-03",
      "name": "Good Friday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-04-05",
      "name": "Easter Sunday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-05",
      "name": "Cinco de Mayo",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-10",
      "name": "Mother's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-25",
      "name": "Memorial Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-06-19",
      "name": "Juneteenth National Independence Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-06-21",
      "name": "Father's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-07-03",
      "name": "Independence Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": true
    },
    {
      "date": "2026-09-07",
      "name": "Labor Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-10-12",
      "name": "Columbus Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-10-31",
      "name": "Halloween",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-11",
      "name": "Veterans Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-26",
      "name": "Thanksgiving Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-27",
      "name": "Black Friday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-24",
      "name": "Christmas Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-31",
      "name": "New Year's Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    }
  ]
}

API reference SDKs Keys and authentication

Every response field

Response fields

countrystring: ISO2 country code
yearinteger: Year returned
monthinteger: Selected month, present on month and day collections
dayinteger: Selected day of month, present on day collections
holidaysarray: Every matching holiday and observance, including multiple names on one date. Empty array for a covered period with no matches
holidays[].datestring: Date, YYYY-MM-DD
holidays[].namestring: Official name, English or the official translation (France stays French)
holidays[].name_localstring or null: Native form when it differs (Japan kanji, Hong Kong and Taiwan Chinese), null otherwise
holidays[].typestring: public for an official day off, observance for cultural days (Halloween, Black Friday)
holidays[].regionsarray or null: Region codes when only part of the country takes the day (GB: ENG, WLS, SCT, NIR), null when nationwide
holidays[].substituteboolean: The day off moved (a holiday falling on a weekend, observed on a weekday)

Build with Holiday

All tutorials →

QUESTIONS

What if there are no matches?: A covered period with no holidays returns an empty holidays array. An unpublished year returns 404 with the published range. Invalid dates and conflicting path and query values return 400.
When do I use which?: Use /holiday/US/2026 for a year or /holiday/US/2026-12 for a month. Both return holidays arrays. A full date path returns the holiday on that day, or null.
Which calendars?: Official published calendars for 150 countries and territories. Many newer calendars cover 2026. Belgium, Denmark and Luxembourg also cover 2027, Lithuania covers 2026-2028, Jersey covers 2025-2027, and Bermuda covers 2026-2029. Calendar entries carry their regional scope. Confirm locally chosen holidays and employer-selected dates for your schedule.
How do I check one date?: GET /holiday/US/2026-12-25 returns the holiday or null. To get every holiday on that date, use /holiday/US?year=2026&month=12&day=25.

See this year's holidays by country in the public holidays tool, or count workdays in the business days calculator.

Know the next holiday.

Public holidays for supported calendars. Every plan.

Start includes 1M API requests a month for $20/mo.

Ready for busy moments.Start includes 1,800 requests per minute, with extra capacity for bursts. Rate limits

Get started Compare plans Read the docs