How holiday data is sourced

Overview

Holiday calendars are deceptively tricky. A “holiday list” is not just a list of names and dates: it’s a set of rules (observance, regional variations, calendar systems, and last-minute proclamations) that must be applied consistently.

This site is designed to be transparent about where dates come from and how to interpret them. This guide explains the sourcing approach and how to cross-check anything that looks uncertain.

What “sourcing” means for holiday calendars

In practice, sourcing usually involves three layers:

1. Rule systems that can compute holidays (e.g., “first Monday in September”).
2. Official announcements that confirm or adjust dates (especially for moveable or lunar-based holidays).
3. Corrections/overrides for edge cases, regional rules, and late changes.

No single source covers everything perfectly for every country, so good calendar data is a blend of automation and verification.

Primary data approach used by this site

This project generates calendars programmatically, then validates and exports them as static data.

A computed holiday engine

Most country calendars are generated using the open-source date-holidays library. This kind of library encodes holiday rules per country/region and computes a year’s dates.

This approach has benefits:

• Consistent logic across many countries
• Repeatable generation for multiple years
• A clear upgrade path when upstream rules are improved

And limitations:

• Some countries have frequent last-minute changes
• Some holidays rely on local observation/announcement
• Regional coverage varies

Overrides for known issues

For a small number of cases, this project applies overrides (country-specific corrections) when needed. Overrides exist to fix issues like:

• A missing holiday in a dataset
• A renamed holiday
• A regional difference not represented upstream
• A confirmed date differing from the computed rule

Validation checks

During builds, the data is validated to ensure:

• Data files exist and parse correctly
• Required fields are present
• Dates are formatted and comparable
• Region data is consistent

Validation does not replace official confirmation, but it helps prevent broken or inconsistent calendars.

Why some holiday dates are “unverified” or uncertain

Some holidays are intrinsically uncertain until confirmed:

• Holidays tied to lunar calendars can vary based on local observation practices.
• Governments may declare one-off holidays late.
• A holiday might be updated by a ministry notice close to the date.

When you see an uncertainty signal, treat it as “plan for possible change.”

How to verify a holiday date (recommended workflow)

1) Start with the country-year calendar

Use the country-year page to see the list, including any observed/substitute dates where available.

2) Check whether a regional calendar applies

If you’re planning for a specific state/province/region, use the region selector. Regional differences are one of the most common reasons people think a date is “wrong.”

3) Confirm with official sources

Depending on the country, “official” might mean:

• Government gazette publications
• Ministry of labour / interior / public service announcements
• Central bank holiday schedule
• Official public sector closure notices

For school scheduling, always check the education department or the published school term calendar.

4) Cross-check with reputable references

Cross-checking is useful when official sources are hard to locate or published late. Prefer reputable, well-maintained references, and confirm again close to the date for holidays that often change.

How exports help reduce mistakes

Manual copying is a major source of errors.

• ICS exports are ideal for Google Calendar, Outlook, and Apple Calendar.
• CSV exports are ideal for spreadsheets, project plans, and operations.

If you’re planning across countries, exporting ensures that everyone uses the same calendar baseline.

What this site does not claim

This site is a planning tool, not a legal guarantee.

• Employers have different policies.
• Observance can vary by sector.
• Governments can change dates.

For anything high-stakes (payroll, compliance, travel, public events), confirm with official local sources.

Explore country calendars

If “How holiday data is sourced” affects schedules or planning, use a small set of country pages as a quick cross-check before you generalize.

• United States — a common reference point for “How holiday data is sourced”.
• United Kingdom — a common reference point for “How holiday data is sourced” in Europe-focused contexts.
• Canada — a practical reference for “How holiday data is sourced” in North America.
• Australia — a practical reference for “How holiday data is sourced” in Oceania.
• India — a practical reference for “How holiday data is sourced” in South Asia.

You can then browse /public-holidays for a broader set of countries relevant to “How holiday data is sourced”.

Sources (starting points)

• date-holidays library: https://github.com/commenthol/date-holidays
• Timeanddate (cross-checking tool): https://www.timeanddate.com/holidays/
• Public holiday definition overview: https://en.wikipedia.org/wiki/Public_holiday

Source hierarchy (how to think about trust)

If you need to decide “what should I believe,” use this hierarchy:

1. Official legal texts and gazettes (most authoritative)
2. Government ministry announcements (often authoritative, sometimes late)
3. Central bank / financial authority calendars (authoritative for banking days)
4. Well-maintained reference aggregators (useful for cross-checking)
5. Secondary summaries (blogs, informal lists)

In many countries, the hardest part is not what the rule is but where it is published.

How changes and corrections happen

Holiday data is a living system.

Upstream updates

Open-source holiday datasets and libraries improve over time as contributors add regions, fix rules, and incorporate official changes.

Local overrides

When a known mismatch exists (for example, a special one-off holiday), this project can apply a local override so the site remains useful even before upstream sources incorporate the change.

Re-checking close to the date

For holidays that are frequently announced late, the best practice is to re-check official sources closer to the date, especially if your decision is high impact.

What you can do if you spot an issue

If a holiday date looks wrong for a country/region/year:

1. Confirm you’re viewing the correct year and the correct region.
2. Check whether the calendar is showing an observed/substitute date.
3. Cross-check with at least one official source (gazette/ministry/central bank).
4. If there is a confirmed discrepancy, capture the evidence (link or screenshot) and report it so the dataset can be corrected.

This workflow keeps the project honest: computed rules for scale, and official confirmation for accuracy.

How the data becomes pages on this site

Because this site is statically exported, it needs the holiday data up front so pages can be generated without a live database.

At a high level:

1. Holiday rules are computed for a country/region/year.
2. The results are written to static JSON under the site’s public/ directory.
3. Pages read the static JSON at build time (or client-side for search) and render calendars.
4. Search and sitemap files are generated so the site remains navigable at scale.

This design makes hosting simple (everything is static files), and it also makes the data auditable: the exported JSON is a “snapshot” of what the site is showing.

What to do if you need maximum accuracy

If your use case is compliance-grade (payroll, contracts, regulated operations), use this site as a planning assistant and always confirm with official sources:

• Government gazette / official legal notices
• Labour ministry announcements
• Central bank/financial authority closure calendars

In other words: use the site for speed and comparison, and use official sources for final sign-off.

Known limitations (so you can plan around them)

Holiday calendars are one of those domains where “mostly right” can still cause real-world friction. Here are the most common limitations to watch for:

Late announcements

Some holidays are announced close to the date. Any dataset generated months in advance may not include those updates yet.

Regional granularity

Even when a country is supported, not every region may be represented with full fidelity. If your work depends on a specific city or province, confirm regional coverage first.

Observed rules are not universal

Observed/substitute policies can change over time, and can differ by sector. A calendar can be “correct” for government offices but not for a specific employer.

Different calendars, different conventions

For moveable religious holidays, two reputable sources can disagree because they follow different calculation or observation conventions. In those cases, official national announcements are the best tie-breaker.

Glossary

• Computed holiday: generated by applying a rule to a year (e.g., “first Monday”).
• Declared holiday: confirmed by a government announcement or proclamation.
• Override: a targeted correction applied when the computed rule doesn’t match a confirmed date.

What gets generated (and how to use it)

If you’re using this site for planning, it helps to know what kinds of outputs are produced:

• Country/year holiday lists: the core calendar view for quick scanning and comparison.
• Exports (ICS/CSV): portable formats you can import into calendars or spreadsheets.
• Search index: a lightweight file that enables fast client-side search across countries and holidays.

The safest workflow is:

1. Find the country and year you care about.
2. Confirm whether observed/substitute dates are shown.
3. Export to ICS (personal/team calendars) or CSV (planning documents).
4. Re-check close to the date for holidays that are frequently announced late.

FAQ

Why doesn’t every holiday have a long explanation on the calendar page?

Calendar pages optimise for scanning and exporting. Deeper background belongs in encyclopedia entries and guides so the calendar stays fast and readable.

Can a holiday be “correct” and still not match my office?

Yes. A public holiday might apply to government offices while private employers choose different policies, or a bank closure calendar might differ from general observance.

What should I do when a government updates a holiday late?

Treat pre-announced calendars as provisional for those cases, and re-check official notices close to the date. If you have evidence of a change, report it so the dataset can be updated.