Overview of the Calendar API

This section introduces the Calendar API and some of its underlying concepts.

The Calendar API is a REST API that can be accessed through explicit HTTP calls or via the Google Client Libraries; the API exposes most of the features available in the Google Calendar Web interface.

Basic concepts

Each Calendar user is associated with a primary calendar and a number of other calendars that they can also access. Users can create events and invite other users, as shown in the following diagram:

Simple model of calendars and events

This example shows two users, Susan A and Wei X. Each has a primary calendar and several other associated calendars. The example also shows two events: an end-of-year presentation and a team offsite.

Here are some facts shown in the diagram:

  • Susan's calendar list includes her primary calendar as well as calendars for her team and cello lessons.

  • Wei's calendar list includes his primary calendar as well as the team calendar, a status tracking calendar, and Susan's primary calendar.

  • The end-of-year presentation event shows Susan as the organizer and Wei as an attendee.

  • The team off-site in Hawaii event has the team calendar as an organizer (meaning it was created in that calendar) and copied to Susan and Wei as attendees.

These concepts: calendars, events, attendees, and others are all explained further in the other sections of this guide:

The rest of this page is devoted to introducing the API resources that you access when using the Calendar API.

API resources

Google Calendar uses the following resources, each detailed in the Reference section of this documentation.

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. For a further explanation of the difference betweeen the Calendars and CalendarList collections, see Calendar and Calendar List

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.