world-wide holidays in gregorian calender

This module provides dates of holidays for various countries, states and regions by type while considering the applicable timezone.

The features are:

• calculation of public, bank and observance holidays for different countries, state, region, following ISO 3166-2
• consideration of timezones for holiday checks
• consideration of start and end time dependent on timezone
• substitute days
• multi-language support for all holiday names
• setting of custom holidays
• uses own grammar for calculation of days
• support for islamic calendar from 1970 to 2080 (islamic dates might not be correct as they are subject to the sighting of the moon)
• support for hebrew calendar from 1970 to 2100
• support for chinese calendar
• for generation of iCal calendar check out date-holidays-ical

Happy holidays!

• Supported Countries, States, Regions
• Usage
• Holiday object
  • Dates
  • Name
  • Types of holidays
• API
• Data
• Custom builds of holidays.json
• Bundling with webpack
• Browser
• CDN
• Contribution and License Agreement
• License
• References

If you are missing holidays from your country, state, region please consider contributing.

Countries: 3
├── BE: Belgique
│   ├── BRU: Bruxelles
│   ├── DE: Deutschsprachige Gemeinschaft
│   ├── VLG: Vlaamse Gemeenschap
│   └── WAL: Communauté française
├── DE: Deutschland
│   ├── BB: Brandenburg
│   ├── BE: Berlin
│   ├── BW: Baden-Württemberg
│   ├── BY: Bayern
│   │   ├── A: Stadt Augsburg
│   │   └── EVANG: Überwiegend evangelische Gemeinden
│   ├── HB: Hansestadt Bremen
│   ├── HE: Hessen
│   ├── HH: Hansestadt Hamburg
│   ├── MV: Mecklenburg Vorpommern
│   ├── NI: Niedersachsen
│   ├── NW: Nordrhein-Westfalen
│   ├── RP: Rheinland-Pfalz
│   ├── SH: Schleswig-Holstein
│   ├── SL: Saarland
│   ├── SN: Sachsen
│   │   └── BZ: Landkreis Bautzen
│   ├── ST: Sachsen-Anhalt
│   └── TH: Thüringen
│       ├── EIC: Landkreis Eichfeld
│       ├── UH: Unstrut-Hainich-Kreis
│       └── WAK: Wartburgkreis
├── FR: France
│   ├── 57: Département Moselle
│   ├── 67: Département Bas-Rhin
│   ├── 68: Département Haut-Rhin
│   ├── YT: Département et région d'outre-mer Mayotte
│   ├── MQ: Département et région d'outre-mer Martinique
│   ├── GP: Département et région d'outre-mer Guadeloupe
│   ├── GF: Département et région d'outre-mer Guyane
│   ├── RE: Département et région d'outre-mer La Réunion
│   ├── MF: Département et région d'outre-mer Saint Martin
│   ├── BL: Département et région d'outre-mer Saint Barthélemy
│   ├── PF: Département et région d'outre-mer Polynésie Française
│   ├── WF: Département et région d'outre-mer Wallis et Futuna
│── └── NC: Département et région d'outre-mer Nouvelle Calédonie

var Holidays = require('date-holidays')
var hd = new Holidays()

// get supported countries
hd.getCountries()
/*>
{ AD: 'Andorra',
  ...
  US: 'United States' }
*/

// get supported states e.g. for US
hd.getStates('DE')
/*>
{  BY: 'Bayern', 
  ...
  TH: 'Thüringen'
}
*/

// get supported regions e.g. for DE, Bayern
hd.getRegions('DE', 'by')
/*>
{ A: 'Stadt Augsburg',
  EVANG: 'Überwiegend evangelische Gemeinden' 
}
*/

// initialize holidays for DE, Bayern, Stadt Augsburg
hd.init('DE', 'by', 'a')
// or using a new instance
hd = new Holidays('DE', 'by', 'a')

// get all holidays for the year 2016
hd.getHolidays(2016)
/*>
[ {
      date: '2016-01-01 00:00:00',
      start: 2015-12-31T23:00:00.000Z,
      end: 2016-01-01T23:00:00.000Z,
      name: 'Neujahr',
      type: 'public',
      rule: '01-01'
    },
  ...
  {
      date: '2016-12-04 00:00:00',
      start: 2016-12-03T23:00:00.000Z,
      end: 2016-12-04T23:00:00.000Z,
      name: '2. Advent',
      type: 'observance',
      rule: '3th sunday before 12-25'
    },,
  ...
 {
      date: '2016-12-31 14:00:00',
      start: 2016-12-31T13:00:00.000Z,
      end: 2016-12-31T23:00:00.000Z,
      name: 'Silvester',
      type: 'bank',
      rule: '12-31 14:00 if sunday then 00:00'
    } ]
*/

// check if date is a holiday while respecting timezones
hd.isHoliday(new Date('2016-02-09 00:00:00 GMT+0000'))
//> false
hd.isHoliday(new Date('2016-02-09 10:00:00 GMT-0600'))
/*>
[{ date: '2016-02-09 00:00:00',
  start: Tue Feb 09 2016 00:00:00 GMT-0600 (CST),
  end: Wed Feb 10 2016 00:00:00 GMT-0600 (CST),
  name: 'Mardi Gras',
  rule: 'easter -47',
  type: 'public' }
]
*/

getHolidays() as well as a matching isHoliday() call return either a list or a single holiday object which consists of:

• {String} date - ISO Date String of (start)-date in local format
• {Date} start - start date of holiday
• {Date} end - end date of holiday
• {String} name - name of holiday using language (if available)
• {String} type - type of holiday public|bank|school|optional|observance
• {Boolean} substitute - (optional) if true holiday substitutes another holiday`
• {String} note - (optional) note`

The date String represents the start date of the holiday in ISO format without timezone. This string it intended for information only.

start and end are the start/end date of the holiday within the selected timezone of the country, state, region.

The name names the holiday in the local language of the selected country, state, region. The applied language(s) can be requested using getLanguages().

The language can be changed using the setLanguages() method. In case that not translation is available a fall-back to the next given language will be made. E.g. local language is "fr", setLanguages('nl') was called. For all holidays where no dutch translation is available the French version will be used instead.

All holiday names should support an English translation.

Currently the following type with their meaning are supported

Additionally a note field is sometimes available for further clarification.

See Holidays API for further information.

All data for the holidays of the different countries is contained in ./data/holidays.json. For changing holiday data edit the appropriate country in ./data/countries. Any details on structure and available grammar for holiday attribution is described in holidays.yaml specification.

If a new public holiday has been added for France (FR), Belgium (BE), or Germany (DE), we will add the holiday to the corresponding YAML file for that country (FR/BE/DE), take a look at ./data/countries/*.yaml.

If the holiday has been added for a specific region or state within France, Belgium, or Germany, we follow this process:

• If the region/state has a dedicated YAML file tied to the country code (FR, BE, or DE), the holiday will be added to that separate file, take a look at ./data/countries/*.yaml.

• If the region/state holidays are included in the main country YAML file, we will place the new holiday in the correct section for that region/state, ensuring it remains within the appropriate country code file (FR/DE/BE).

Add the public holiday to the appropriate ./data/countries/*.yaml file, including its translations: e.g. :

 09-27:
    name:
        de: Tag der Französischsprachigen Gemeinschaft
        fr: La fête de la communauté française
        nl: Feestdag van de Franse Gemeenschap

Alternatively, if the holiday is a common public holiday across multiple countries, try to add it to the appropriate ./data/countries/*.yaml file. e.g. :

10-09:
  _name: Abolition of Slavery

and include its translations in the separate ./data/names.yaml file.

Abolition of Slavery:
    name:
      en: Abolition of Slavery
      fr: Abolition de l’esclavage
      nl: Afschaffing van de slavernij
      de: Abschaffung der Sklaverei
      vi: Bãi bỏ chế độ Nô lệ

If only selected countries are required in data/holidays.json you can add the following script to your npm scripts section. e.g. for picking just BE, DE, do the following:

"scripts": {
  "build": "holidays2json --pick BE,DE --min"
},

The --min switch removes dependencies which are not required for the countries selected. You may not be able to use the full set of rules in case you want to add custom rules.

Alternatively you may use the --omit option.

Manually use

npx holidays2json --pick BE,DE --min

NOTE: There are some countries which depend on data of others which might render the file useless. e.g. "YT" requires "FR", so try to pick or omit all states for the FR Country Code

npx holidays2json --pick FR,FR-57,FR-67,FR-68,YT,MQ,GP,GF,RE,MF,BL,PF,WF,NC --min

NOTE: To pick or omit all countries, states and regions of FR, DE, BE, do this.

npx holidays2json --pick FR,FR-57,FR-67,FR-68,YT,MQ,GP,GF,RE,MF,BL,PF,WF,NC,BE,DE --min

To minimize bundle sizes consider adding the following lines in your webpack config. Please take a look at ./webpack.config.js. To further reduce size consider custom builds by only selecting required countries.

...
  plugins: [
    new webpack.IgnorePlugin({
      checkResource (resource, context) {
        // ---- do not bundle astronomia vsop planet data
        if (/\/astronomia\/data$/.test(context)) {
          return !['./deltat.js', './vsop87Bearth.js'].includes(resource)
        }
        // ---- do not bundle moment locales
        if (/\/moment\/locale$/.test(context)) {
          return true
        }
        return false
      }
    })

This project also runs in all modern browsers. See ./examples/browser

Please do not forget to set the correct charset!

<html>
<head>
  <!-- set page-wide -->
  <meta charset="UTF-8">
  ...
</head>
<body>
  ...
  <!-- or per script -->
  <script src="your-bundle.js" charset="UTF-8"></script>

Minified distribution bundles are available via https://unpkg.com

NOTE: dist-bundles are quite huge in size ~1.5MByte so use custom builds instead.

See https://unpkg.com/date-holidays/dist/

• index.min.js: commonjs2 bundle
• umd.min.js: umd bundle

You like to contribute please read CONTRIBUTING.md.

If you contribute code to this project, you are implicitly allowing your code to be distributed under the ISC license. You are also implicitly verifying that all code is your original work or correctly attributed with the source of its origin and license.

Copyright (c) 2016- commenthol (ISC License)

The data contained in holidays.json and ./data/countries/*.yaml is available under CC BY-SA 3.0 as the majority of data obtained relies on wikipedia articles. The required attribution can be found inside the files ./data/countries/*.yaml.

See LICENSE for more information.

• CONTRIBUTING.md
• date-holidays-ical
• date-holidays-parser
• Holidays API
• holidays.yaml specification
• LICENSE