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.
Table of Contents
Installation
MANUAL INSTALLATION
- Download the
calendarific.zipfile from the latest release. - Unpack the release and copy the
custom_components/calendarificdirectory into thecustom_componentsdirectory of your Home Assistant installation. - Configure the
calendarificplatform - 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
calendarificplatform. - 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-WLSPlatform 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 DaySensor 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/ |