Calendars API
chevron down
 

Calendars API

Variable: calendars

Type: CalendarProvider

The Calendar API allows developers to retrieve events from user's calendars.

import calendars from "calendars";

let start = new Date()
start.setHours(0, 0, 0, 0)
let end = new Date()
end.setHours(23, 59, 59, 999)

let eventsQuery = { startDate: start, endDate: end }

calendars.searchEvents(eventsQuery).then(function() {
   todayEvents.forEach(event => {
     console.log(event.title)
   })
}

Interface: CalendarProvider

The CalendarProvider interface provides information about the installed calendars on the mobile app and user's current events in those calendars. This will provide methods to easily get current calendars and the events for those calendars from a start date until an end date.

Methods

searchCalendars()

searchCalendars(query?: CalendarsQuery | undefined)

Returns: Promise<Calendar[]>

Retrieve the calendars.

searchEvents()

searchEvents(query: EventsQuery)

Returns: Promise<Event[]>

Retrieve events.

searchSources()

Returns: Promise<Source[]>

Retrieve the available sources.

Interface: EventsQuery

Structure used to query for events.

Events that span across the whole range (or bleed into it) are returned as well.

All-day events will be interpreted in local timezone during filtering, so a query with startDate set to 2017-01-01T00:00:00±(local offset) will never return a New Year's Eve event from 2006.

If the date range between startDate and endDate is greater than four years, it is shortened to the first four years.

Properties

calendarIds

string[] or undefined

endDate

Date

startDate

Date

Interface: CalendarsQuery

Structure used to filter the calendars.

Properties

sourceIds

string[] or undefined

Interface: Attendee

An Attendee object represents a participant in a calendar event. An attendee can be a person, group, room, or other resource.

Properties

readonly name

string

The attendee's name.

readonly status

AttendeeStatus

The attendee's participation status.

Interface: AbsoluteAlarmTrigger

Properties

date

Date

The absolute date of the alarm.

Interface: RelativeAlarmTrigger

Properties

offset

number

Offset of the alarm in milliseconds to the start or end of the event.

"start" or "end"

The date to which the offset relates to (the start or the end of the event).

Interface: Alarm

An alarm associated with an event.

Properties

trigger

RelativeAlarmTrigger or AbsoluteAlarmTrigger

The trigger of the alarm.

type

string

The type of the alarm.

AppleAlarmTypes

String: string

Alarm types on iOS devices.

The most common type is "display".

The list is not exhaustive and other types might be reported by the OS.

AndroidAlarmTypes

String: string

Alarm types on Android devices.

The most common types are "default" and "alarm".

The list is not exhaustive and other types might be reported by the OS.

Interface: Event

The entry from a calendar.

Properties

readonly alarms

Alarm[]

The alarms associated with the event.

readonly attendees

Attendee[]

The attendees associated with the event, as an array of Attendee objects.

readonly calendarId

string

The identifier of the associated Calendar for this event.

readonly description

string or undefined

Notes or description of the event.

readonly endDate

Date

The end date for the event.

All-day events are returned in the UTC time zone.

The end date of an all-day event is always midnight of the day after the event.

readonly id

string

A unique identifier for the event object.

readonly isAllDay

boolean

True, if the event is an all-day event.

An all-day event is special kind of event that is only bound to a date (range) but independent of time and time zone. Birthdays and holidays are good examples for all-day events.

The startDate and endDate properties of an all-day event will have their time component set to midnight (00:00:00) and their timezone set to UTC.

Since many methods on Date objects return values for the local time it is important to use the getUTC... methods to query the range of an all-day event.

readonly location

string or undefined

Location of the event.

readonly organizer

Attendee or undefined

The organizer of this event.

readonly recurrenceRule

string or undefined

The recurrence rule of the event (if any).

The rule is a string formatted like an iCalendar Recurrence Rule (RECUR).

readonly sourceId

string

The identifier of the associated Source for this event.

readonly startDate

Date

The start date of the event.

All-day events are returned in the UTC time zone.

readonly status

EventStatus

Current status of the event.

readonly title

string

Title of the event.

readonly userStatus

UserStatus

Current participation status of the user for this event.

Enum: EventStatus

The event status

Members

Canceled

The event is canceled.

Confirmed

The event is confirmed.

Tentative

The event is tentative.

Unknown

The event has unknown status.

UserStatus

String: AttendeeStatus.Unknown | AttendeeStatus.Tentative | AttendeeStatus.Accepted | AttendeeStatus.Decl...

Participation's status used for current user.

Enum: AttendeeStatus

The participant’s attendance status

Members

Accepted

The participant has accepted the event.

Declined

The participant has declined the event.

Delegated

The participant has delegated attendance to another participant.

Pending

The participant has yet to respond to the event.

Tentative

The participant’s attendance status is tentative.

Unknown

The participant’s attendance status is unknown.

Interface: Calendar

A calendar object that holds multiple events.

One or more calendars are usually associated with a source.

Properties

readonly id

string

A unique identifier for the Calendar object.

readonly sourceId

string

Id of the source that the calendar belongs to.

readonly title

string

Title of the calendar.

Interface: Source

The account that a calendar belongs to (example: Yahoo, Gmail).

Properties

readonly id

string

A unique identifier for the Source object.

readonly title

string

Title of the source.