My favorites | English | Sign in

Google Calendar APIs and Tools

API Reference Guide

Important: This is an old version of this page. For the latest version, use the links in the left-side navbar.

This document provides detailed reference documentation for the Google Calendar Data API.

Contents

  1. Audience
  2. Calendar feed types
    1. Calendar feeds
    2. Event feeds
    3. Comment feeds
    4. Personal settings feeds (Experimental)
    5. Visibility values
    6. Projection values
  3. Calendar query parameters reference
  4. Calendar elements reference
    1. GCal namespace element reference
    2. GAcl namespace element reference

Audience

This document is intended for programmers who want to write client applications that can interact with Google Calendar.

It's a reference document; it assumes that you understand the concepts presented in the developer's guide, and the general ideas behind the Google Data APIs protocol.

Calendar feed types

Google Calendar provides a variety of representations of calendar data. There are two independent axes for specifying a representation: visibility and projection.

Visibility values indicate whether the representation is publicly visible or not. For example, a visibility value of public indicates that the representation is publicly visible. For a list of values, see Visibility values, below.

Projection values indicate how much and what kind of information is included in the representation. For example, a projection value of basic indicates that the representation is a basic Atom feed without any extension elements. For a list of values, see Projection values, below.

Calendar feeds

There are three feeds that return a collection of calendar entries: the metafeed, the allcalendars feed, and the owncalendars feed.

The metafeed is a private, read-only feed that contains an entry for each calendar that a user has access to. The URL for the metafeed is:

http://www.google.com/calendar/feeds/default

The allcalendars feed is a private read/write feed that is used for managing subscriptions and personalization settings of a user's calendars. Unlike the metafeed, the allcalendars feed is writable, so calendar entries can be inserted and deleted, which is equivalent to subscribing and unsubscribing to existing calendars. Calendar entries in the allcalendars feed can also be updated, but since a user may not own all the calendars in this feed, only personalization settings can be updated with this feed. You can update the following personalization settings of a calendar using the allcalendars feed:

Property Description
color Specifies the color of the calendar in the UI.
hidden Indicates whether or not the calendar is shown in the UI.
selected Indicates whether or not the calendar is selected in the UI.

For more information about interacting with the allcalendars feed, see the Managing Subscriptions section of the Developer's Guide. The URL for the allcalendars feeds is:

http://www.google.com/calendar/feeds/default/allcalendars/full

The owncalendars feeds is a private read/write feed that can be used to manage calendars that a user owns. A user is an owner of a calendar if they either created the calendar or if they were granted ownership by an existing owner of the calendar. For the allcalendars feed, inserting and deleting calendar entries is equivalent to creating and deleting secondary calendars. Since a user owns all the calendars in the ownclendars feed, properties such as the title and summary can be updated using this feed. For more information about interacting with the owncalendars feed, see the Managing Calendars section of the Developer's Guide. The URL for the owncalendars feed is:

http://www.google.com/calendar/feeds/default/owncalendars/full

Since all the calendar feeds are private, you can only access it using an authenticated request. That is, the request must contain an authentication token for the user whose calendars you want to retrieve. The Calendar Data API Developer's Guide contains more information about authentication.

Event feeds

To request a particular representation of an event feed, you specify both a visibility value and a projection value in the URI that you send to Calendar.

The URI of a representation of an event feed takes the following form:

http://www.google.com/calendar/feeds/userID/visibility/projection

For example, the following URI is for a feed of calendar events with private visibility and full projection:

http://www.google.com/calendar/feeds/jo@gmail.com/private/full

As a developer, you may want to use any of the projections, but you'll normally use only two of the visibility levels: public or private.

For a private feed, instead of specifying an ID for userID, you can specify the special value default, which tells Calendar to use the default calendar for the username and password that you provided during authentication. For an example of using a default feed, see the Creating single-occurrence events example.

If you know an event's ID, you can request a specific event rather than a full feed. The URI of a representation of a specific Calendar entry (with a given event ID) takes the following form:

http://www.google.com/calendar/feeds/userID/visibility/projection/eventID

Some feed types are read/write (that is, you can post new events to them, and edit or delete existing events), while others are read-only. Read-only feeds don't include a <link rel="http://schemas.google.com/g/2005#post"> element (to tell you where to post new events), and events in read-only feeds don't include <link rel="edit"> elements.

Comment feeds

An event can have a subfeed of comments attached to it, representing notes provided by attendees responding to an event invitation. In a full projection event feed, the event feed doesn't include the comments feed inline; instead, the event feed provides a link to the comments feed, with a URL of the following form:

http://www.google.com/calendar/feeds/userID/visibility/full/eventID/comments/subfeedEntryID

The subfeed entry ID at the end is optional; if you include it, then Calendar returns the specified comment entry instead of a feed.

In a composite projection, the event feed does include the comments feed inline. For more information, see Projection values, below.

Personal Settings feed (Experimental)

The settings feed is a private, read-only feed that contains user preferences for Calendar. It is a representation of Calendar General Settings page in Calendar UI.

The URI for settings feed has the following form:

http://www.google.com/calendar/feeds/userID/settings

You can only fetch settings feed for the userID corresponding to the currently authenticated user (or use default as userID). Each user preference is represented as a name/value pair. A given user preference entry with known name can be retrieved with the following URI:

http://www.google.com/calendar/feeds/userID/settings/preferenceName

Each settings feed entry has an gCal:settingsProperty element which has the name and value of particular user preference.

Visibility values

The following table describes the supported visibility values:

Visibility Description Updatability Security Notes
public Shows only public events. Always read-only. Does not require authentication. Inaccessible if the user turns off sharing.
private Shows both public and private events. Potentially read/write. Requires authentication. Updatable only by authorized users.
private-magicCookie Shows both public and private events. Always read-only. Does not require authentication. Instead, authentication information is embedded within the feed URI in the magicCookie string. The magic cookie is a random, high-entropy string combined with authentication information.

Projection values

Although the examples in this document use only the full projection, there are a variety of other useful projections. You may want to start by using full, and then try other projections as you need them and as you get more comfortable with interacting with Calendar.

The following table describes the supported projection values:

Projection Name Description Updatability
full Full-fidelity feed; contains all event properties, but comments aren't included inline; instead, they're specified (in the <gd:feedLink> element) as a link to a separate comment feed. Potentially read/write.
full-noattendees Same as full, but without any <gd:who> elements. Potentially read/write.
composite Same as full, but additionally contains inlined comments, in an <atom:feed> element inside the <gd:feedLink> element. The composite feed also contains <gd:recurrenceException> elements inline in recurring events, and each of those exception elements contains a <gd:originalEvent> element pointing to the original recurring event. Note that the composite feed is often significantly longer than the full feed. Always read-only.
attendees-only Attendees-only feed. Contains minimal event information, but includes <gd:who>. Always read-only.
free-busy Free/busy feed. Contains minimal event information, but includes <gd:when>. Always read-only.
basic Basic Atom feed without any extension elements. Its <atom:summary> and <atom:content> properties contain pre-rendered HTML. Always read-only.

Calendar query parameters reference

In addition to the standard Data API query parameters, Calendar uses the following optional parameters:

Parameter Meaning Notes
futureevents A shortcut to request all events that are scheduled for future times. Overrides the recurrence-expansion-start, recurrence-expansion-end, start-min, and start-max values. Valid values are true (return all future events) or false (ignore this parameter). Default is false.
orderby Specifies order of entries in a feed.

Currently, the only supported values are lastmodified (the default) and starttime.

If you add orderby=lastmodified as a query parameter, then the returned feed's entries are ordered by their <updated> values, which is the default ordering.

If you add orderby=starttime as a query parameter, then the returned feed's entries are in order by the <gd:when> element's starttime attribute.
recurrence-expansion-start Specifies beginning of time period for which to expand recurring events.
  • Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00.
  • The lower bound is inclusive, whereas the upper bound is exclusive.
recurrence-expansion-end Specifies end of time period for which to expand recurring events.
singleevents Indicates whether recurring events should be expanded or represented as a single event. Valid values are true (expand recurring events) or false (leave recurring events represented as single events). Default is false.
sortorder Specifies direction of sorting. Valid values are ascending (with synonyms ascend and a) and descending (with synonyms descend and d).
start-min Together with start-max creates a timespan such that only events that are within the timespan are returned. If not specified, default start-min is 1970-01-01.
  • Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00.
  • The lower bound is inclusive, whereas the upper bound is exclusive.
  • Events that overlap the range are included.
start-max Together with start-min creates a timespan such that only events that are within the timespan are returned. If not specified, default start-max is 2031-01-01.
ctz The current timezone. If not specified, times are returned in UTC.
  • Times in the resulting feed will be represented in this timezone.
  • Replace all spaces with underscores (e.g. "ctz=America/Los_Angeles").

To receive a feed of all events that overlap with a given time period, set start-min to the beginning of the period and start-max to the end of the period.

In fact, it's usually a good idea to specify start-min and/or start-max to limit the results you get back.

If the user's calendar contains recurring events, then the returned feed includes information about all recurring-event instances that overlap the specified time period.

Specifically, each recurring event is represented by a <gd:recurrence> element in the result feed, and each of those elements includes a <gd:when> element for each occurrence of that event that falls between the start time and the end time. Looking at <gd:when> elements is much simpler than parsing recurrences and exceptions yourself, so in general if you want to handle recurring events it's a good idea to specify start-min and/or start-max.

For example, say you specify a start-min value of 2006-04-01T00:00:00 and a start-max value of 2006-04-20T23:59:59, and the user's calendar includes a weekly meeting that takes place every Monday in 2006. Then the returned feed will include all the events (single or recurring events) that occur within or overlap with that period, plus any event that contains <gd:when> elements for the meetings on 2006-04-03, 2006-04-10, and 2006-04-17—each of the Mondays within the given date range.

For more information about recurring events and how they're handled by services, see the Common Elements: "Kinds" document.

Calendar does not support Data API category queries. It does support full-text queries, using the standard Data API q query parameter; it searches all of the text fields in events, except for extended properties. It also supports the other standard Data API query parameters. For more information about those parameters, see the Google Data API protocol reference document.

Note: The max-results query parameter for Calendar is set to 25 by default, so that you won't receive an entire calendar feed by accident. If you want to receive the entire feed, you can specify a very large number for max-results.

Calendar elements reference

In addition to the standard Data API elements, Calendar uses elements described in the Common Elements document.

Specifically, each entry in a Calendar feed is an Event kind. Each event may contain any or all of the following:

  • One or more <gd:who> elements that represent people associated with the event, each of whom is described with a Contact kind.
  • A <gd:comments> element that points to a feed containing Message kinds.
  • One or more <gd:extendedProperty> elements to store custom data. For example, synchronization tools may find it useful to store non-Calendar event IDs as extended properties. In Calendar, an extended property name must be no more than 44 characters long, and an extended property value must be no more than 1024 characters long.

There are a few differences between the <feed> element used by the Calendar Data API and the <feed> element used by other Google Data APIs. Specifically:

  • In Calendar, the <author> element of a feed is required. (In other Google Data APIs, it's optional).
  • In Calendar, the <atom:link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/> element is required for updatable feeds.

Also, Calendar supports a few rel and type attribute values for <atom:link> that aren't used in other Google Data APIs:

rel and type value Description
atom:link[@rel='alternate'][@type='text/calendar'] Specifies the URL of the ICS source of the calendar, if it came from an ICS source.
atom:link[@rel='source'][@type='application/atom+xml'] Specifies the URL of the Data API source of the calendar, if it came from a Data API source.
atom:link[@rel='related'] Specifies a URL related to the feed.
atom:link[@rel='http://schemas.google.com/gCal/2005/webContent'] [@type='type'] Specifies "web content" for an event; for more information, see gCal:webContent.

Finally, the Calendar <entry> element may optionally contain an <atom:source> element, which isn't used in entries in other Google Data APIs.

GCal namespace element reference

Google Calendar provides several extension elements for use in a metafeed (the feed that lists the user's calendars). These elements are in the gCal namespace, not the Google Data namespace, because they're specific to Calendar.

gCal:accesslevel

Indicates what level of access the current user (the one whose credentials are being used to request the metafeed) has to the calendar.

Properties

Property Type Description
@value xs:string

Must be one of the following:

none
Current user has no access to the calendar.
read
Current user has read-only access to the calendar.
freebusy
Current user can see only the free/busy information on the calendar, not the details of events.
editor
Current user has full edit access to the calendar, except that they can't change the calendar's access control settings.
owner
Current user has full owner access to the calendar.
root
Available only in Google Apps domains. User is a domain administrator, and therefore has full owner access to the calendar regardless of access control settings.

Example

A calendar for which the current user has full owner access:

<gCal:accesslevel value="owner" />

Schema

start = accesslevel

accesslevel =
  element gCal:accesslevel {
    attribute value { xs:string }
  }

gCal:color

The color used to highlight a calendar in the user's browser.

Properties

Property Type Description
@value xs:string Must be one of the following hexadecimal RGB color values:
#A32929 #B1365F #7A367A #5229A3 #29527A #2952A3 #1B887A
#28754E #0D7813 #528800 #88880E #AB8B00 #BE6D00 #B1440E
#865A5A #705770 #4E5D6C #5A6986 #4A716C #6E6E41 #8D6F47

Example

A color:

<gCal:color value="#A32929" />

Schema

start = color

color =
  element gCal:color {
    attribute value { xs:string }
  }

gCal:hidden

Indicates whether a calendar is visible or not.

Properties

Property Type Description
@value xs:boolean Is calendar visible?

Example

A hidden calendar:

<gCal:hidden value="true" />

Schema

start = hidden

hidden =
  element gCal:hidden {
    attribute value { xs:boolean }
  }

gCal:selected

Indicates whether calendar is selected.

Properties

Property Type Description
@value xs:boolean Is calendar selected?

Example

A selected calendar:

<gCal:selected value="true" />

Schema

start = selected

selected =
  element gCal:selected {
    attribute value { xs:boolean }
  }

gCal:settingsProperty (Experimental)

Represents a key/value pair from the selected user's Calendar settings.

Settings

Name Description Value Format Examples
locale Currently selected Calendar interface language. ISO 639-1 Language Code. en_GB
en_US
country User country selected for time zone display. ISO two-letter country code. US
GB
timezone User time zone. This is not a time zone of any calendar, but the time zone in which events appear on Calendar UI. Long format time zone ID (not PST, but America/Los_Angeles. America/Los_Angeles
UTC
Europe/Prague
timezoneLabel Custom time zone label if specfied by user. Arbitraty string or empty if not set. My time zone label
Home
displayAllTimezones Indicates whether all time zones are visible in Calendar Settings regardless of selected country. true or false. true
false
dateFieldOrder User's desired date format to use in Calendar UI. One of the following values: DMY (day/month/year), MDY, YMD. DMY
MDY
format24HourTime Indicates whether 24-hour format is used in Calendar UI. true or false. true
false
weekStart Indicates the day of the week that the week starts on in Calendar UI. 0 to 6 integer, 0 for Sunday. 0
6
defaultCalMode The default calendar view to display. day for day view, week for week view, month for month view, list for agenda view, custom for custom view. See customCalMode property. week
custom
customCalMode The number of days to display in custom calendar view mode. custom,days where days is the number of days to display. custom,7
custom,28
userLocation User location, used to display weather. Arbitrary string (common is city name or ZIP code). Empty if not set. Mountain View
93043
weather Whether to show weather based on location, and weather format to use. Empty string if weather is not shown. C for Celsius, F for Fahrenheit format. C
F
showDeclinedEvents Whether to display declined events. true or false. true
false
hideInvitations Whether to hide event invitations which are not yet accepted. true or false. true
false
alternateCalendar Whether alternate calendar view is used and which one. 0 if alternate view is not used. 1 for standard Hijri calendar, 2 for Kuwaiti Hijri calendar, 3 for Saudi Hijri calendar. 0
1

Properties

Property Type Description
@name xs:string Indicates the name of the current setting. See the table above for possible settings and their valid values.
@value xs:string Indicates the value of the current setting.

Example

<gCal:settingsProperty name="timezone" value="America/Los_Angeles"/>

Schema

start = sequence

sequence =
element gCal:settingsProperty {
  attribute name { xs:string },
  attribute value { xs:string }
}

gCal:sequence

Indicates the revision sequence number of the event as defined in Section 4.8.7.4 of RFC 2445. Must be non-negative.

Properties

Property Type Description
@value xs:integer Indicates the revision sequence number of the event.

Example

<gCal:sequence value='1' />

Schema

start = sequence

sequence =
  element gCal:sequence {
    attribute value { xs:integer }
  }

gCal:syncEvent

Indicates whether this is a sync scenario where we allow setting the gCal:uid, the gCal:sequence, and the organizer of an event.

This element makes sense only when inserting and updating events. This element should primarily be used in a sync scenario.

Properties

Property Type Description
@value xs:boolean Indicates whether this is a sync scenario or not.

Example

<gCal:syncEvent value="true" />

Schema

start = syncEvent

syncEvent =
  element gCal:syncEvent {
    attribute value { xs:boolean }
  }

gCal:timezone

A time zone.

Properties

Property Type Description
@value xs:string A time zone ID.

Example

A time zone:

<gCal:timezone value="America/Los_Angeles" />

Schema

start = timezone

timezone =
  element gCal:timezone {
    attribute value { xs:string }
  }

gCal:timesCleaned

The number of times the specified calendar has been completely cleared of events.

Properties

Property Type Description
@value xs:integer The number of times the calendar has been cleared of events

Example

<gCal:timesCleaned value="2" />

Schema

start = timesCleaned

timesCleaned =
  element gCal:timesCleaned {
    attribute value { xs:integer }
  }

gCal:uid

Indicates the globally unique identifier (UID) of the event as defined in Section 4.8.4.7 of RFC 2445.

Must be a globally unique string and must follow specifications in Section 4.8.4.7 of RFC 2445.

Properties

Property Type Description
@value xs:string Indicates the globally unique identifier (UID) of the event.

Example

<gCal:uid value='t9d6o9stha0j0cblaoi4s5l29c' />

Schema

start = uid

uid =
  element gCal:uid {
    attribute value { xs:string }
  }

gCal:webContent

Information about a Calendar Event Gadget, formerly called a web content event. The web content icon appears at the top of a day on a calendar; clicking the icon opens a pop-up window that displays the Calendar Event Gadget. Multiple <gCal:webContentGadgetPrefs> elements can be used to specify user preferences for the gadget.

Note: This element appears only inside a webContent <link> element.

atom:link Properties for webContent

Property Type Description
@rel xs:string Must be "http://schemas.google.com/gCal/2005/webContent".
@title xs:string Human-readable title to appear in the header of the pop-up window, and in the tooltip for the icon.
@href xs:string URL of the icon to display. Icon can be in any image format that can be displayed in a web browser. Image will be scaled to 16 pixels square.
@type xs:string Specifies the type of the content. Allowed values are "application/x-google-gadgets+xml", "text/html", and "image/imageformat", where imageformat is a format name like gif or png.

gCal:webContent Properties

Property Type Description
@height xs:integer Height (in pixels) of the <iframe> or <img> element.
@url xs:string URL of the content to display in the pop-up window. The content can be a gadget, an HTML file or an image, as long as you set the type attribute correctly in the webContent <link> element.
@width xs:integer Width (in pixels) of the <iframe> or <img> element.

gCal:webContentGadgetPrefs Properties

Property Type Description
@name xs:string Name of the gadget user preference.
@value xs:string Value of the gadget user preference.

Example

The DateTime gadget (in green):

<link rel="http://schemas.google.com/gCal/2005/webContent"
      href="http://www.google.com/favicon.ico"
      title="DateTime Gadget (a classic!)"
      type="application/x-google-gadgets+xml">
  <gCal:webContent url="http://google.com/ig/modules/datetime.xml" width="300" height="136">
    <gCal:webContentGadgetPref name="color" value="green" />
  <gCal:webContent>
</link>

Schema

start = webContentLink

webContentLink =
  element atom:link {
    attribute rel { xs:string },
    attribute href { xs:string },
    attribute title { xs:string },
    attribute type { xs:string },
    element gCal:webContent {
      attribute height { xs:integer },
      attribute url { xs:string },
      attribute width { xs:integer }
      element gCal:webContentGadgetPref {
        attribute name { xs:integer },
        attribute value { xs:integer }
      }*
    }
  }

GAcl namespace element reference

Google defines the Google Data API ACL namespace as http://schemas.google.com/acl/2007. We recommend using the namespace alias gAcl.

Google currently defines two elements in the gAcl namespace:

  • gAcl:scope
  • gAcl:role

Each element appears exactly once in every rule.

gAcl:scope

Defines which set of users are governed by the rule that contains this element.

Properties

Property Type Description
@type xs:string

Must be one of the following:

user
Indicates that this access rule applies to an individual. The value attribute is an email address.
domain
Available only in Google Apps For Your Domain. Indicates that this access rule applies to all users with email addresses in your domain, which allows you to (for example) create calendars that are shared with everyone in your domain. The value attribute should contain your domain name.
default
Indicates that this access rule applies to all users. There is no value attribute.
@value? xs:string

An email address or a domain name, depending on the value of the type attribute.

If a given user matches multiple scopes, then they can perform any operation allowed by any of the levels they have been granted in any scope. Consider an ACL with the following rules:

  • user darcy@gmail.com has the role read
  • default has the role freebusy

Given those rules, user darcy@gmail.com can perform any operation allowed by the read or freebusy access levels.

Example

A specific user:

<gAcl:scope type="user" value="darcy@gmail.com" />

Schema

start = scope

scope =
  element gAcl:scope {
    attribute type { xs:string },
    attribute value { xs:string }?
  }

gAcl:role

Defines an access level that applies to all users specified in the associated <gAcl:scope>.

Properties

Property Type Description
@value xs:string

Every role value listed below, other than none, must start with the namespace http://schemas.google.com/gCal/2005#. For example, read in the below list must appear as http://schemas.google.com/gCal/2005#read. The none value doesn't have a prefix; it's in the gAcl namespace.

The value must be one of the following:

none
The specified users have no rights.
read
The specified users have read-only access to the calendar.
freebusy
The specified users can see only the free/busy information on the calendar, not the details of events.
editor
The specified users have full edit access to the calendar, except that they can't change the calendar's access control settings.
owner
The specified users have full owner access to the calendar.
root
Available only in Google Apps For Your Domain. The specified users have administrator access to the calendar server.

Example

To indicate that the specified users can edit the calendar but can't change ACL settings:

 <gAcl:role value='http://schemas.google.com/gCal/2005#editor'></gAcl:role>

Schema

start = role

role =
  element gAcl:role {
    attribute value { xs:string }
  }

 

 

Back to top