Calendarific

The 'Calendarific' component is a Home Assistant custom sensor which counts down to public holidays and observances, by querying the Calendarific api

State Returned:

The number of days remaining to the next occurance.

Attributes (both are provided by the Calendarific api):

date: The next date of the holiday (formatted by date_format configuration option if set)
description: The description of the holiday.

Installation
- Manual Installation
- Installation via HACS
Platform Configuration
- Platform Configuration Parameters
Sensor Configuration
- Sensor Configuration Parameters

Installation

MANUAL INSTALLATION

Download the calendarific.zip file from the latest release.
Unpack the release and copy the custom_components/calendarific directory into the custom_components directory of your Home Assistant installation.
Configure the calendarific platform
Restart Home Assistant.
Configure sensors either in the configuration.yaml or by using the integrations page

INSTALLATION VIA HACS

Ensure that HACS is installed.
Search for and install the "calendarific" integration.
Configure the calendarific platform.
Restart Home Assistant.
Configure sensors either in the configuration.yaml or by using the integrations page

Platform Configuration

You will need an API key from Calendarific.com Go to the sign up page and open a new account. A free tier account is limited to 1000 api calls per month. This integration will make two calls per day (and two on home assistant start)

The Calendarific platform MUST be configured in the configuration.yaml file.

# Example configuration.yaml platform entry
calendarific:
  api_key: YOUR_API_KEY
  country: GB
  state: GB-WLS

Platform configuration parameters

Attribute	Optional	Description
`api_key`	No	your api key from calendarific.com
`country`	No	your country code here is a list of supported countries
`state`	Yes	your state code (ISO 3166-2 subdivision code) [USA] [UK] note the state code is for the country in the uk (counties not supported) or the state in the us. If omitted, only national holidays will be displayed

Sensor Configuration

Individual sensors can be configured using Config flow or in configuration.yaml:

Config Flow

In Configuration/Integrations click on the + button, select Calendarific and configure the options on the form (The available holidays will automatically appear on the list if the platform was configured correctly in the above step).

configuration.yaml

Add calendarific sensor in your configuration.yaml. The following example adds two sensors - New Year's Day and Christmas Day (Note that these must be entered EXACTLY as they are on the Calendarific server)

# Example configuration.yaml sensor entry
sensor:
  - platform: calendarific
    holiday: New Year's Day
  - platform: calendarific
    holiday: Christmas Day

Sensor Configuration Parameters

Attribute	Optional	Description
`holiday`	No	Name of holiday provided by calendarific api
`name`	Yes	Friendly name Default: Holiday name
`icon_normal`	Yes	Default icon Default: `mdi:calendar-blank`
`icon_today`	Yes	Icon if the holiday is today Default: `mdi:calendar-star`
`days_as_soon`	Yes	Days in advance to display the icon defined in `icon_soon` Default: 1
`icon_soon`	Yes	Icon if the holiday is 'soon' Default: `mdi:calendar`
`date_format`	Yes	formats the returned date Default: '%Y-%m-%d' for reference, see http://strftime.org/

pinkywafer / Calendarific