Public holiday calendar
See this year's public holiday calendar and the next holiday for a supported country or region. Choose a region where offered to include the dates that apply there, rather than only nationwide or shared dates.
Published public holidays for this calendar.
Loading the calendar…
Choose the calendar that applies to your location
Holiday dates can vary by state, province, or other region. A nationwide or shared-date selection can contain fewer dates than a regional calendar. The US federal-employee calendar also has a different scope from a promise that every business is closed.
Public holidays, observances, and substitute dates
A public-holiday label identifies a designated holiday in the selected calendar. An observance marks an occasion without necessarily creating a day off. The list distinguishes these types.
When a calendar publishes a substitute or observed date, use that listed date for scheduling. Time off and office closures still depend on the organization and its working arrangements.
Take the selected holiday calendar with you
Copy a single date for a booking or leave request. Download CSV to plan in a spreadsheet, or import the .ics file into a calendar app. Each file uses the year and scope shown above the list, retaining public-holiday, observance, and substitute labels.
Calendar imports are all-day snapshots. They do not subscribe to later updates. The year menu offers reviewed available years and a current-year lookup. Coverage varies by country. A failure to find the next holiday does not remove an annual calendar that has already loaded.
Build a public holiday calendar
Filter the Holiday API calendar for the chosen country and region, then find the next public holiday. If the year has no remaining holiday, check the next year.
- Load the selected country and year.
- Use public holidays whose region applies to the visitor.
- Compare date strings in the chosen local calendar and handle the next-year boundary.
Installation steps are included in each example. Set PARSEAPI_KEY on your server. Swift and Kotlin use an app key restricted to your app ID.
// npm install @parseapi/sdk@1.14.0
import { parseAPI } from '@parseapi/sdk';
// Set PARSEAPI_KEY on your server.
const parse = parseAPI();
const country = 'GB', region = 'ENG', timeZone = 'Europe/London';
const parts = new Intl.DateTimeFormat('en-US', {
timeZone, year: 'numeric', month: '2-digit', day: '2-digit',
}).formatToParts(new Date());
const part = name => parts.find(value => value.type === name).value;
const today = part('year') + '-' + part('month') + '-' + part('day');
const year = Number(today.slice(0, 4));
async function publicHolidays(year) {
const calendar = await parse.holiday(country, { year });
if (calendar.country !== country || calendar.year !== year || !Array.isArray(calendar.holidays)) {
throw new Error('Holiday calendar unavailable.');
}
return calendar.holidays.filter(row => row.type === 'public' &&
(row.regions === null || row.regions.includes(region)))
.sort((a, b) => a.date.localeCompare(b.date));
}
const holidays = await publicHolidays(year);
let next = holidays.find(row => row.date >= today) ?? null;
if (!next) next = (await publicHolidays(year + 1))[0] ?? null;
console.log({ country, region, year, holidays, next });
Export the selected browser calendar
// Pass the validated selected annual response and its exact displayed scope.
// holidayCalendarCsv(calendar, scope) and holidayCalendarIcs(calendar, scope) return snapshot text.
// scope = {countryName, region, regionName, scope}; do not widen regional coverage.
const DAY_MS = 86400000;
function businessDateDay(value) {
if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
return null;
const [year, month, day] = value.split('-').map(Number);
if (year < 1)
return null;
const date = new Date(0);
date.setUTCFullYear(year, month - 1, day);
if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day)
return null;
return date.getTime() / DAY_MS;
}
function businessDateAfter(value, days) {
const start = businessDateDay(value);
if (start === null || !Number.isInteger(days))
throw new Error('Enter a valid date.');
return new Date((start + days) * DAY_MS).toISOString().slice(0, 10);
}
function object(value) {
return value !== null && typeof value === 'object' && !Array.isArray(value);
}
function readHolidayCalendar(data, country, year) {
const fail = () => new Error(`Could not verify the ${year} holiday calendar.`);
if (!object(data) || data.country !== country || data.year !== year
|| !Array.isArray(data.holidays) || !data.holidays.length)
throw fail();
const holidays = data.holidays.map((value) => {
if (!object(value))
throw fail();
const { local_name, ...row } = value;
// A customer key can retain API 1.0.0. Explicit current nulls still win.
return { ...row, name_local: Object.hasOwn(value, 'name_local') ? value.name_local : local_name };
});
for (const row of holidays) {
if (!object(row) || typeof row.date !== 'string' || businessDateDay(row.date) === null
|| Number(row.date.slice(0, 4)) !== year || typeof row.name !== 'string' || !row.name.trim()
|| (row.name_local !== null && typeof row.name_local !== 'string')
|| (row.type !== 'public' && row.type !== 'observance') || typeof row.substitute !== 'boolean'
|| (row.regions !== null && (!Array.isArray(row.regions) || !row.regions.length
|| !row.regions.every((region) => typeof region === 'string' && /^[A-Z0-9]{1,3}$/.test(region)))))
throw fail();
}
return { ...data, holidays };
}
function checked(calendar, scope) {
const answer = readHolidayCalendar(calendar, calendar.country, calendar.year);
if (!scope.countryName.trim() || !scope.scope.trim())
throw new Error('The calendar scope is unavailable.');
// The export must use the selected annual response, never widen a region.
if (answer.holidays.some(row => row.regions !== null && (!scope.region || !row.regions.includes(scope.region)))) {
throw new Error('The returned holidays do not match the selected region.');
}
return answer;
}
function csvCell(value) {
let text = String(value);
if (/^[\s]*[=+\-@]/.test(text))
text = `'${text}`;
return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
}
function holidayCalendarCsv(calendar, scope) {
const answer = checked(calendar, scope);
return '\uFEFF' + [
['date', 'name', 'name_local', 'type', 'regions', 'substitute', 'country', 'year', 'selected_region', 'scope'],
...answer.holidays.map(row => [row.date, row.name, row.name_local ?? '', row.type, row.regions?.join('; ') ?? '', row.substitute, answer.country, answer.year, scope.region, `${scope.regionName || scope.countryName}: ${scope.scope}`]),
].map(row => row.map(csvCell).join(',')).join('\r\n') + '\r\n';
}
function icsText(value) {
return value.replaceAll('\\', '\\\\').replace(/\r\n|\r|\n/g, '\\n').replaceAll(';', '\\;').replaceAll(',', '\\,');
}
/** RFC 5545 folding counts UTF-8 octets, including a continuation's leading space. */
function foldLine(line) {
const encoder = new TextEncoder();
const lines = [];
let current = '';
let bytes = 0;
for (const char of line) {
const length = encoder.encode(char).length;
if (bytes + length > 75) {
lines.push(current);
current = ' ';
bytes = 1;
}
current += char;
bytes += length;
}
return [...lines, current].join('\r\n');
}
function holidayCalendarIcs(calendar, scope, exportedAt = new Date()) {
const answer = checked(calendar, scope);
if (!Number.isFinite(exportedAt.getTime()))
throw new Error('The export time is invalid.');
const timestamp = exportedAt.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
const identity = `${scope.countryName}${scope.regionName ? ` · ${scope.regionName}` : ''} ${answer.year}`;
const lines = ['BEGIN:VCALENDAR', 'VERSION:2.0', 'PRODID:-//ParseAPI//Holiday calendar//EN', 'CALSCALE:GREGORIAN',
`X-WR-CALNAME:${icsText(identity)}`, `X-WR-CALDESC:${icsText(scope.scope)}`];
for (const row of answer.holidays) {
const description = [identity, scope.scope, row.type === 'public' ? 'Public holiday' : 'Observance',
...(row.substitute ? ['Published substitute date'] : []), ...(row.name_local && row.name_local !== row.name ? [row.name_local] : []),
...(row.regions ? [`Applies in ${row.regions.join(', ')}`] : [])].join('\n');
lines.push('BEGIN:VEVENT', `UID:${encodeURIComponent(`${answer.country}|${scope.region}|${answer.year}|${row.date}|${row.name}|${row.type}`)}@parseapi.com`, `DTSTAMP:${timestamp}`, `DTSTART;VALUE=DATE:${row.date.replaceAll('-', '')}`, `DTEND;VALUE=DATE:${businessDateAfter(row.date, 1).replaceAll('-', '')}`, `SUMMARY:${icsText(row.name)}`, `DESCRIPTION:${icsText(description)}`, 'TRANSP:TRANSPARENT', 'END:VEVENT');
}
return [...lines, 'END:VCALENDAR'].map(foldLine).join('\r\n') + '\r\n';
}
How do I find the next public holiday?
Select your country or territory and the applicable region. For the current year, the next matching public holiday appears first with its date, weekday, and days remaining. Observances do not replace the next public-holiday answer.
Can I see another year's holiday calendar?
The year menu includes the reviewed years available for the selected country as well as the current-year lookup. Future coverage varies by calendar. If a year is unavailable, the tool says so rather than inventing dates. The next-holiday countdown is shown only while viewing the current year.
Does a public holiday mean every business or bank is closed?
No. The selected calendar describes a particular national, federal, or regional scope. Employer arrangements, sector rules, local dates, and individual leave can differ. US federal-employee holidays are not a promise that every private business is closed.
What is the difference between a public holiday and an observance?
A public holiday is designated as such in the selected calendar. An observance marks an occasion without necessarily creating time off. Each listed date and the downloaded files keep that distinction.
Why does a holiday appear on a substitute date?
Some calendars publish a different observed date when a holiday falls on a weekend or under another scheduling rule. The tool marks published substitute dates and does not invent an automatic replacement for every weekend holiday.
How do I copy dates or add holidays to my calendar?
Use Copy date beside an occasion to copy YYYY-MM-DD. Download CSV for the selected year and scope, or download the .ics file and import it into your calendar app. The files include the selected scope, observances, and substitute labels. The .ics file is an all-day snapshot, not a live subscription.
Why is this year's list visible when the next holiday is unavailable?
The annual calendar and the next-holiday search are separate results. A lookup for a later year can fail even after this year's calendar loaded successfully. You can still use, copy, and download the loaded annual list.