node-red-contrib-german-holidays for NodeRED

This node are for getting holidays or information if today/tomorrow/... is a holiday. This can be used for smart home.

The Holidays can be setup as fixed dates or dates based on Easter, Advent. Pre defined Holidays for german exists, but these must not be used.

⚠️ Warning! Version 1.0 breaks to existing! ⚠️

Requires Node-Red 1.0 or later!

Changed payload (holiday* instead of holiday*)!

Not configured Holidays will not be used (no backwards compatibility). Existing nodes needs to be opened, saved and deployed once!

Installation

npm install node-red-contrib-german-holidays

Quick Start

Simple flow:

[{"id":"2607227a.3c983e","type":"german-holidays","z":"c4313d2c.5d102","region":"SN","x":360,"y":100,"wires":[["dcaacec7.e1eb"]]},{"id":"dcaacec7.e1eb","type":"debug","z":"c4313d2c.5d102","name":"Holidays","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","x":560,"y":100,"wires":[]},{"id":"d2ed4078.52011","type":"inject","z":"c4313d2c.5d102","name":"","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"05 00 * * *","once":false,"onceDelay":0.1,"x":150,"y":100,"wires":[["2607227a.3c983e"]]}]

Implemented Nodes

holidays Node -get holidays on any input

How to use

Configuration possibilities

there are 2 lists one for definition of Holidays and one for special days which are not Holidays.

Under the lists are Buttons to fill the lists with pre defined Holidays for German and Austria. If all is selected, all holidays are used (independent if they are really for all regions are available) and id "allgemeine" are used only holidays will be considered which are available in all regions of Germany.

Options for the incoming message object

The incoming message is mainly used for trigger the calculation. This will be done typically once per day. Nevertheless you have the following possibility's to configure the working of the node by the following properties of the incoming messages:

ts, msg.ts defines a timestamp for the source (today) for calculation of the data. if not defined today will be used.
day, msg.day if defined only the Holiday information will get the relative to the timestamp (today by default). So if msg.ts is not defined, msg.day = 0 is today, msg.day = -1 is yesterday; msg.day = 1 is tomorrow, ... Additionally the output will be a day object only representing this day.
date, msg.date if defined only the Holiday information for the defined date will given. If this is given, the output will be only a day object representing this day.
year, msg.year if defined only the Holiday information for the defined year will given. Will only work if no msg.date or msg.ts are in the input message, because otherwise the year information from there will be used.
region, msg.region the region which should be used for getting holidays. If this property is in the input message only the holidays of the region will be considered and nit the setup holidays in the configuration of the node. This property must be a string of two letters with the German state shortcut (BY=Bayern, BE=Berlin, ...).

generic day object day-object

base object for a day representation

id string an id of the object
name string name of the day.
nameAlt string alternative name of the day if defined.
dayOfWeek string the day of the week, where 1 is Monday.
day number the day in month of the day
month number the month of the day, where 0 in January and 11 is December.
naturalMonth number the month of the day, where 1 in January and 12 is December.
year number the year of the day.
date number the day as JavaScript date.
dateString string the date of the day as string.
dateISOString string the date of the day as ISO string.
data any optional only available if additional data is set.

enhanced day object enh-day-object

if the input property day or date was set, the payload is only a day object with the following properties. Otherwise the payload is a more complex object for different days which are of type day-object (see below).

This object has all properties of the generic day object:

id string an id of the object. If it is a holiday the holiday.id, if it is a special day specialday.id, otherwise equal to type[0].id.
name string name of the day. If it is a holiday the holiday.name, if it is a special day specialday.name, otherwise equal to type[0].name.
nameAlt string alternative name of the day if defined. If it is a holiday the holiday.nameAlt, if it is a special day specialday.nameAlt, otherwise equal to type[0].nameAlt.
type array array of objects, where first element represents the day of week.
type[0].id string id of the day of week.
type[0].name string name of the day of week.
type[0].nameAlt string alternate name of the day of week.
isSaturday boolean is true if the day is Saturday.
isSunday boolean is true if the day is Sunday.
isHoliday boolean is true if the day is a holiday.
holiday day-object only available if the day is a holiday. (isHoliday is true.) Then the representation of the specific holiday.
isSpecialday boolean is true if the day is a special day.
specialday day-object only available if the day is a special day. (isSpecialday is true.) Then the representation of the specific special day.
isWeekend boolean is true if the day is Sunday or Saturday.
isSunOrHoliday boolean is true if the day is Sunday or a holiday.
isWeekendOrHoliday boolean is true if the day is Sunday, Saturday or a holiday.
isHolidayOrSpecialday boolean is true if the day is a holiday, or a special day.
(optional) dayOffset number the offset to today in days (not every time available)
(optional) isBetweenSundayAndHoliday string is true if the day is a Monday when Tuesday is a holiday (only available on standard output for today, tomorrow and dayAfterTomorrow).
(optional) isBetweenHolidayAndSaturday string is true if the day is a Friday when Thursday is a holiday (only available on standard output for today, tomorrow and dayAfterTomorrow).
(optional) isBetweenWeekendOrHoliday string is true if the day is not a Saturday, Sunday or a holiday, but the day before or after is Saturday, Sunday or a holiday (only available on standard output for today, tomorrow and dayAfterTomorrow).
(optional) data any optional only available if additional data is set.

Output message object

if the input has no day or date property (default use case) the the payload is an object with the following properties

msg.payload.yesterday enh-day-object day-object for the day before today.
msg.payload.today enh-day-object day-object for today.
msg.payload.tomorrow enh-day-object day-object for the day after today.
msg.payload.dayAfterTomorrow enh-day-object day-object for the day after tomorrow.
msg.payload.afterTheDayAfterTomorrow enh-day-object day-object for the day after tomorrow.
msg.payload.next object object representing information about the next holiday.
msg.payload.next.holiday enh-day-object object representing the next holiday.
msg.payload.next.holidays array array of the next 10 holiday (msg.payload.next.holidays.0 is equal to msg.payload.next.holiday), every enh-day-object has additional a diffDays property which is the count of days until this holiday and a diff which represents the difference in milliseconds.
msg.payload.next.holidayDiff number count of days until next holiday.
msg.payload.next.specialday enh-day-object object representing the next special day.
msg.payload.next.specialdays array array of the next 10 special days (msg.payload.next.specialdays.0 is equal to msg.payload.next.specialday), every enh-day-object has additional a diffDays property which is the count of days until this holiday and a diff which represents the difference in milliseconds.
msg.payload.next.weekendDay enh-day-object object representing the next Saturday or Sunday (if it is Saturday).
msg.payload.next.weekendDayDiff number count of days until next Saturday or Sunday (if it is Saturday).
msg.payload.next.weekendOrHoliday enh-day-object object representing the next holiday or Saturday or Sunday (next free day).
msg.payload.next.weekendOrHolidayDiff number count of days until next holiday or Saturday or Sunday (next free day).
msg.payload.holidays enh-day-object An array of objects for every Holiday in the year.
msg.payload.holidays array An array of objects for every Holiday in the year.
msg.payload.holidaysNum array An array of numbers for every Holiday in the year.
msg.payload.weekNumber number weekNumber for today.
msg.payload.weekNumberEven boolean Is true if the weekNumber is even.
(optional) msg.payload.data any is the same as msg.payload.today.data and only available if additional data is available for today.

Usage

Typically the node will be triggered at once every day and the result will be persistent in a global context. Then with a switch node the flows can be controlled by the usage of the properties of the object output. Examples for using this node:

shutter can be opened/closed on different timestamps based if today or tomorrow is a holiday
dimmer can set to different brightness based if it is a Holiday

[{"id":"2607227a.3c983e","type":"german-holidays","z":"c4313d2c.5d102","name":"","region":"SN","x":420,"y":140,"wires":[["dcaacec7.e1eb","15259bce.575154"]]},{"id":"dcaacec7.e1eb","type":"debug","z":"c4313d2c.5d102","name":"Holidays","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","x":620,"y":100,"wires":[]},{"id":"d2ed4078.52011","type":"inject","z":"c4313d2c.5d102","name":"","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"05 00 * * *","once":false,"onceDelay":0.1,"x":150,"y":100,"wires":[["2607227a.3c983e"]]},{"id":"e4912846.3a1ca8","type":"inject","z":"c4313d2c.5d102","name":"","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"","once":true,"onceDelay":"1","x":150,"y":180,"wires":[["2607227a.3c983e"]]},{"id":"1ab3e37c.4d15fd","type":"comment","z":"c4313d2c.5d102","name":"every day at midnight","info":"","x":180,"y":60,"wires":[]},{"id":"869da82f.484e48","type":"comment","z":"c4313d2c.5d102","name":"once on Node-Red start","info":"","x":180,"y":140,"wires":[]},{"id":"15259bce.575154","type":"change","z":"c4313d2c.5d102","name":"","rules":[{"t":"set","p":"day-info","pt":"global","to":"payload","tot":"msg"}],"action":"","property":"","from":"","to":"","reg":false,"x":650,"y":180,"wires":[[]]},{"id":"d2fe809f.3c90d","type":"switch","z":"c4313d2c.5d102","name":"","property":"day-info.today.isWeekendOrHoliday","propertyType":"global","rules":[{"t":"true"},{"t":"else"}],"checkall":"true","repair":false,"outputs":2,"x":410,"y":300,"wires":[["c73a89b5.6630f8"],["e245c8da.585928"]]},{"id":"26326493.2e010c","type":"inject","z":"c4313d2c.5d102","name":"","topic":"","payload":"true","payloadType":"bool","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":150,"y":300,"wires":[["d2fe809f.3c90d"]]},{"id":"c73a89b5.6630f8","type":"debug","z":"c4313d2c.5d102","name":"is Weekend or Holiday","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","x":660,"y":300,"wires":[]},{"id":"e245c8da.585928","type":"debug","z":"c4313d2c.5d102","name":"is not a Weekend and not a Holiday","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","x":700,"y":360,"wires":[]},{"id":"e427d079.51212","type":"comment","z":"c4313d2c.5d102","name":"Example for usage in switch node","info":"","x":210,"y":260,"wires":[]}]

Bugs and Feedback

For bugs, questions and discussions please use the GitHub Issues.

💰 Donations

Even for those that don't have the technical knowhow to help developing on there are ways to support development. So if you want to donate some money please feel free to send money via PayPal.

LICENSE

Licensed under the MIT License (MIT) License. (See LICENCE file) This was developed by using the https://github.com/sfakir/feiertagejs.

TODO

[] allow more then one holiday and special day for a day. (currently only one are allowed)

Other

this node is published also here: