Hide

Google Apps Calendar API Concepts and Use Cases

The Google Calendar API allows a program to perform many of the operations available via Google Calendar web interface. Using this API, it is possible to search for and view public calendar events. Authenticated sessions can access private calendars, as well as create, edit, and delete both events and the calendars that contain them.

Sites or applications that wish to have a deeper integration with Google Calendar can leverage the Google Calendar API. Such an integration could be a web application that creates or displays Calendar data. It could be a desktop application that synchronizes a user's Calendar with an existing desktop application. It could even be a device that brings the Calendar experience to a new platform.

To get started by creating a small but functional client application using the Google Calendar API, follow the steps in one of our quickstart tutorials.

Calendar concepts

Google Calendar is built on several basic concepts:

Event
An event on a calendar containing information such as the title, start and end times, and attendees. Events can be either single events or recurring events. An event is represented by an Event resource. The Events collection for a given calendar contains all event resources for that calendar.
Calendar
A calendar is a collection of events. Each calendar has associated metadata, such as calendar description or default calendar time zone. The metadata for a single calendar is represented by a Calendar resource. The Calendars collection contains Calendar resources for all existing calendars.
Calendar List
A list of all calendars on a user's calendar list in the Calendar UI. The metadata for a single calendar that appears on the calendar list is represented by a CalendarListEntry resource. This metadata includes user-specific properties of the calendar, such as its color or notifications for new events. The CalendarList collection contains all CalendarListEntry resources for a given user. See also a further explanation of the difference betweeen the Calendars and CalendarList collections.
Setting
A user preference from the Calendar UI, such as the user's time zone. A single user preference is represented by a Setting Resource. The Settings collection contains all Setting resources for a given user.
ACL
An access control rule granting a user (or a group of users) a specified level of access to a calendar. A single access control rule is represented by an ACL resource. The ACL collection for a given calendar contains all ACL resources that grant access to that calendar.
Color
A color presented in the Calendar UI. The Colors resource represents the set of all colors available in the Calendar UI, in two groups: colors available for events and colors available for calendars.
Free/busy
A time when a calendar has events scheduled is considered "busy", a time when a calendar has no events is considered "free". The Freebusy resource allows querying for the set of busy times for a given calendar or set of calendars.

About event resources

This section describes different features provided by the Google Calendar API to work with Event resources such as:

Timed events
Events taking place between two specific points in time.
All-day events
Events lasting entire day(s).
Recurring events
Events repeating at a set interval.
Reminders
Reminders for events.
Events with attendees
Managing events with multiple attendees.

Timed events

A timed event has its start and end dateTime fields set to the start and end times of the event:

"start": {
  "dateTime": "startTime",
  # Optional
  "timeZone": "America/Los_Angeles"
},
"end": {
  "dateTime": "endTime",
  # Optional
  "timeZone": "America/Los_Angeles"
},

Such an event starts at startTime and ends at endTime (exclusive).

The dateTime field is a string representing a date-time in the (RFC 3339) format "yyyy-mm-ddTHH:MM:ssZZ" with an optional milliseconds component. The time offset might also be omitted if a valid IANA time zone ID is provided in the timeZone field. This exception is limited to startTime and endTime and doesn't apply to other date-time fields in the API.

The following are examples of valid date-time values:

  • 2011-06-03T10:00:00 — no milliseconds and no offset.
  • 2011-06-03T10:00:00.000 — no offset.
  • 2011-06-03T10:00:00-07:00 — no milliseconds with a numerical offset.
  • 2011-06-03T10:00:00Z — no milliseconds with an offset set to 00:00.
  • 2011-06-03T10:00:00.000-07:00 — with milliseconds and a numerical offset.
  • 2011-06-03T10:00:00.000Z — with milliseconds and an offset set to 00:00.

All-day events

An all-day event has its start and end date fields set to the days of the event:

"start": {
  "date": "startDate",
},
"end": {
  "date": "endDate",
},

Such an event starts on startDate and ends the day before endDay. For example, a one-day event should have its start date set to day and its end date set to day + 1.

Recurring events

The main difference between a single occurrence event and a recurring event resides in the recurrence field set in a recurring event:

"recurrence": [
  "RRULE:FREQ=WEEKLY;UNTIL=20110701T160000Z",
  # EXRULE, RDATE, EXDATE...
],

The recurrence field is an array of strings defining an RRULE, EXRULE, RDATE or EXDATE rule as defined by the RFC 2445 and lets the API and client applications understand how the event will repeat itself after its original start and end dates.

The events.instances method lets client applications retrieve a list of occurrences of a recurring event.

Important: The start.timeZone and end.timeZone elements are required and must be equal when inserting recurring events.

For more information, see Create Recurring Events.

Event reminders

The Google Calendar API allows client applications to set reminders for events:

"reminders": {
  "useDefault": "useDefault",
  # Overrides can be set if and only if useDefault is false.
  "overrides": [
      {
        "method": "reminderMethod",
        "minutes": "reminderMinutes"
      },
      # ...
  ]
}

If useDefault is set to:

  • true — the event uses the calendar's default reminders which can be retrieved at the top of an Events collection when retrieving events or in the CalendarListEntry resource.
  • false — the event uses custom reminders specified in the overrides field.

Events with multiple attendees

A user can invite other users to an event by including them in the attendees event property when inserting or updating the event. Each attendee will see a copy of the event in their calendar. By setting the sendNotifications parameter in the insert or update request to true, the attendees will also receive an email notification. The user that owns the original event is called the organizer of the event.

The attendee copy of the event has the same event ID as the organizer copy, and most of its properties are identical, except for private properties of the event such as event reminders, colorId, transparency, or the extendedProperties.private property. Whenever the organizer changes any of the shared properties, such as the event start time, summary or location, the change is reflected in each attendee's copy of the event. The attendees can also change the shared properties of the event, but the changes are only reflected on the attendee's own copy. The only event change that is propagated from the attendees back to the organizer is the attendee's response status, stored in the attendees[].responseStatus property.

The events.import method adds a private copy of an event to a given calendar. No other users specified in the attendees[] or organizer property will receive a copy of the event on their calendar.

The organizer of an event can be changed using the API method events.move. The actor performing the method must have write access to both the source and target calendars.

About calendarList entry resources

A calendar in a user's calendar list is a calendar that is visible in the Google Calendar web interface under My calendars or Other calendars:

The calendarList API methods lets client applications retrieve information about those calendars and other metadata such as whether or not the calendar is displayed, or its color.

Calendars collection vs CalendarList collection

Calendars is a collection of all existing calendars. It allows for creation and deletion of calendars. It can also be used to access and modify those calendar properties which are visible and shared across all users with access to the calendar. Examples of such global properties are the calendar title or its default time zone.

CalendarList is a collection of all calendar entries that a user has added to their list (shown in the left panel of the web UI). Operations are available for modifying this list as well as retrieving and setting user-specific calendar properties. Examples of such properties are foreground color or override reminders. For example, each user can have a different color for the same calendar.

Here's a comparison of operations for both collections:

Operation Calendars CalendarList
insert Creates a new secondary calendar. By default, this calendar is also added to the creator's calendar list. Inserts an existing calendar into the user's list.
delete Deletes a secondary calendar. Removes a calendar from the user's list.
get Retrieves calendar metadata e.g. title, time zone. Retrieves metadata plus user-specific customization e.g. color, override reminders.
patch/update Modifies calendar metadata. Modifies user-specific calendar properties.

Send feedback about...

Google Calendar API