Search by task, endpoint, field, or error.

← Docs

Holiday API

Public holidays by country, year, month, or day.

List published holidays and cultural observances for a country, then narrow the calendar to a month or day. Records include the date, name, regional scope, and whether a substitute date moved the holiday. The type field distinguishes official public holidays from cultural observance dates.

Collections always return a holidays array, including every record when multiple holidays share a date. A covered period with no matches returns an empty array. An unpublished year returns 404 with the published range. Calendars are never extrapolated.

Year

GET
api.parseapi.com/holiday/{country}
Year collection. Optional year, month, and day query filters
Explore
Parameters 4
countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · optional

Four-digit published year, defaults to the current UTC year. Must match a path year when supplied.

Range: 1 to 9999

monthinteger · query · optional

Filter the collection by month. Must match a path month when supplied.

Range: 1 to 12

dayinteger · query · optional

Filter by day of month. Requires month and a real calendar date. Must match a path day when supplied.

Range: 1 to 31

GET
api.parseapi.com/holiday/{country}/{year}
Year path alias, for example /holiday/US/2026
Explore

Omit year for the current UTC year. Add month to narrow the collection.

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.holiday("US", { year: 2026 });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "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
    }
  ]
}

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)

Month

GET
api.parseapi.com/holiday/{country}/{year}-{month}
Month collection. Same result as ?year=2026&month=12
Explore

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

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

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "country": "US",
  "year": 2026,
  "month": 12,
  "holidays": [
    {
      "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
    }
  ]
}

Day collection

Use year, month, and day query filters for every holiday on a date. Day requires month. You can also add day to a month path.

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

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

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "country": "US",
  "year": 2026,
  "month": 12,
  "day": 25,
  "holidays": [
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    }
  ]
}

Use YYYY, YYYY-MM, or YYYY-MM-DD in paths. Months and days in paths need two digits. Invalid dates and conflicting path and query values return 400 with guidance. Matching values are allowed.

One date

The full date path keeps its existing response. holiday is one matching record, or null for a covered date with no match. A public holiday takes priority when the date has multiple records. Use the day collection to keep every name. A missing holiday does not establish a working day.

GET
api.parseapi.com/holiday/{country}/{date}
One date, YYYY-MM-DD. The holiday object, or holiday: null
Explore
Parameters 5
countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

datestring · path · required

YYYY, YYYY-MM, or YYYY-MM-DD. Path months and days require two digits. Full dates must be real calendar dates.

Pattern: ^\d{4}(?:-\d{2}){0,2}$

yearinteger · query · optional

Four-digit published year, defaults to the current UTC year. Must match a path year when supplied.

Range: 1 to 9999

monthinteger · query · optional

Filter the collection by month. Must match a path month when supplied.

Range: 1 to 12

dayinteger · query · optional

Filter by day of month. Requires month and a real calendar date. Must match a path day when supplied.

Range: 1 to 31

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.holiday.date("US", "2026-10-31");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

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

Response fields

countrystring
ISO2 country code
datestring
Date checked
holidayobject or null
The holiday on that date (same shape as holidays[]), or null

Native names

Japan pairs the official English name with kanji in name_local, back to 1955.

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.holiday("JP", { year: 1955 });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "country": "JP",
  "year": 1955,
  "holidays": [
    {
      "date": "1955-01-01",
      "name": "New Year's Day",
      "name_local": "元日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-01-15",
      "name": "Coming of Age Day",
      "name_local": "成人の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-03-21",
      "name": "Vernal Equinox Day",
      "name_local": "春分の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-04-29",
      "name": "Emperor's Birthday",
      "name_local": "天皇誕生日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-05-03",
      "name": "Constitution Memorial Day",
      "name_local": "憲法記念日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-05-05",
      "name": "Children's Day",
      "name_local": "こどもの日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-09-24",
      "name": "Autumnal Equinox Day",
      "name_local": "秋分の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-11-03",
      "name": "Culture Day",
      "name_local": "文化の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-11-23",
      "name": "Labor Thanksgiving Day",
      "name_local": "勤労感謝の日",
      "type": "public",
      "regions": null,
      "substitute": false
    }
  ]
}

Build with Holiday

All tutorials →

Questions? Email