eartharoid/holidays

Data and APIs for public/bank holidays.

🚧 Work in progress 🚧

https://github.com/workalendar/workalendar/blob/master/workalendar/europe/united_kingdom.py https://github.com/workalendar/workalendar/blob/master/workalendar/europe/united_kingdom.py https://www.ukbankholidays.co.uk/ https://en.wikipedia.org/wiki/Wedding_of_Princess_Anne_and_Mark_Phillips https://en.wikipedia.org/wiki/Public_holidays_in_the_United_Kingdom

Holidays

Data and APIs for public/bank holidays in supported countries.

Why?

To add a minor feature to one of my other projects, I needed a simple way to check if today is a holiday that worked for most countries, and I wasn't satisfied with the existing solutions. Unfortunately, holidays are not as simple as they seem (cough Scotland).

What's wrong with existing solutions?

Most of them work, but after looking at several open-source projects that calculate dates, I was stuck thinking about how the code would be better represented as data.

• https://www.gov.uk/bank-holidays.json: only works for the UK
• Nager.Date: accurate, but the API isn't flexible enough to overcome regional inconsistencies, not multi-lingual
• holidayapi.com: stupidly expensive
• timeanddate.com: probably very good, but even more stupidly expensive
• Azure Open Datasets: difficult to access, probably doesn't get updated
• enrico: weird API and uses XML
• python-holidays: excellent, but I didn't want to make an API in python
• workalendar: good, but python again
• date-holidays: FINALLY! someone decided to make data with rules instead of code.... but not well. In my opinion, its far more confusing and difficult to follow or update than any of the solutions above that use code

Goals and scope

There have been many changed and additional UK holidays in the last few years, so this was made with the following goals in mind:

Limitations

• Although it can be if someone does the research, this shouldn't be expected to be historically accurate.
• https://www.officeholidays.com/countries/united-kingdom https://support.google.com/calendar/answer/6084659

HTTP API

Data for the last decade, the current decade, and the next decade (currently 2010-2039 inclusive) is available for supported countries with the free API.

Read the documentation →

Libraries

JavaScript

@eartharoid/holidays

This provides some helper functions for working with the computed data, such as getting the next holiday, checking if today is a holiday, etc.

Must be paired with @eartharoid/holidays-calculator or pre-computed data (e.g. @eartharoid/holidays-static) to be useful.

@eartharoid/holidays-calculator

This is the core library that calculates the dates of holidays in a given year using the rules data. It is used to generate the static data files in dist and @eartharoid/holidays-static.

@eartharoid/holidays-static

Pre-computed data, as in dist, ready for use with @eartharoid/holidays.

Static files

You can use these JSON files in your non-JavaScript projects. All of the last decade, the current decade, and the next decade is available (currently 2010-2039 inclusive). The files are available in the dist directory and can be downloaded from the CDN:

https://cdn.jsdelivr.net/gh/eartharoid/holidays/dist/v1/[year]/[country].json

e.g. https://cdn.jsdelivr.net/gh/eartharoid/holidays/dist/v1/2023/gb.json

Warning You should update local copies at least every 3 months to ensure new holidays are included.

Countries

Please consider sponsoring (or donating to) your country's contributors.

• United Kingdom (GB) - @eartharoid

Contributing

Please help to add countries and missing or incorrect holidays.

Read the contributing guidelines for more information.

License

Data (data/*.yml, dist/v1/*.json, and output from the library and API) is available under the Open Database License.

Everything else is licensed under the MIT License.