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:

A single event on a calendar containing information such as the title of event, start and end times, and attendees.
A set of metadata, such as a description, for a single calendar.
Calendar List
A list of all calendars on a user's calendar list in the Calendar UI.
A user preference from the Calendar UI, such as the user's time zone.
A single access control rule containing information such as the type and scope of the rule.
A list of colors presented in the Calendar UI, in two groups: for events and calendars.
A set of times, for a set of calendars, where the calendar does not have any events.

Google Calendar API data model

A resource is an individual data entity with a unique identifier. The Google Calendar API operates on five types of resources:

Event Resource
Represents a single event on a calendar.
Calendars Resource
Represents metadata for an individual calendar.
CalendarList Resource
Represents metadata for an individual calendar that appears on the user's calendar list in the UI.
Settings Resource
Represents a single user preference from the Calendar UI.
ACL Resource
Represents an ACL.
Color Resource
Represents the list of colors from the Calendar UI.
Free/busy Resource
Represents free/busy times for a set of calendars.

The Google Calendar API data model is based on groups of resources, called collections:

Events Collection
Consists of all the Event Resources within a specific Calendar Resource.
Calendars Collection
Consists of all the Calendar Resources for a specific user.
CalendarList Collection
Consists of all the CalendarList Resources for a specific user.
Settings Collection
Consists of all the Settings Resources for a specific user.
ACL Collection
Consists of all the ACL Resources applied to a specific calendar.

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 for events.

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:ss" with an optional milliseconds and offset elements. The following examples are valid 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.

If an offset is not provided when creating, importing or updating an event, the timeZone field has to be set to a valid time zone value.

All-day events

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

"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": [

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.

Special API endpoints let client applications:

  • Retrieve a list containing occurrences of the events.

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 — client applications have the ability to set custom reminders for the event in the overrides field.

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.

Send feedback about...

Google Calendar API