Skip to main content

Calendar Entity

A calendar entity is an entity that represents a set of events with a start and end date and/or time, helpful for automations. A calendar entity is derived from the homeassistant.components.calendar.CalendarEntity.



Properties should always only return information from memory and not do I/O (like network requests). Implement update() or async_update() to fetch data.

eventCalendarEventNotImplementedErrorThe current or next upcoming CalendarEvent or None.


STATE_ONThe calendar has an active event.
STATE_OFFThe calendar does not have an active event.


Get Events

A calendar entity can return events that occur during a particular time range. Some notes for implementors:

  • The start_date is the lower bound and applied to the event's end (exclusive).
  • The end_date is the upper bound and applied to the event's start (exclusive).
  • Recurring events should be flattened and returned as individual CalendarEvent.
class MyCalendar(CalendarEntity):

async def async_get_events(
hass: HomeAssistant,
start_date: datetime.datetime,
end_date: datetime.datetime,
) -> list[CalendarEvent]:
"""Return calendar events within a datetime range."""


A CalendarEvent represents an individual event on a calendar.

startdatetime or dateRequiredThe start (inclusive) of the event. Must be before end. Both start and end must be the same type. As a datetime, must be in UTC timezone.
enddatetime or dateRequiredThe end (exclusive) of the event. Must be after start. As a datetime, must be in UTC timezone.
summarystringRequiredA title or summary of the event.
locationstringNoneA geographic location of the event.
descriptionstringNoneA detailed description of the event.