Related Links

Using the Google Calendar Data API

Google Calendar allows client applications to view and update calendar events in the form of Google data API ("GData") feeds. Your client application can use the Google Calendar data API to create new events, edit or delete existing events, and query for events that match particular criteria.

There are many possible uses for the Calendar data API. For example, you can create a web front end for your group's calendar that uses Google Calendar as a back end. Or you can generate a public calendar for Google Calendar to display, based on your organization's event database. Or you can search relevant calendars to display a list of upcoming events on those calendars.

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

This document assumes that you understand the general ideas behind the Google data APIs protocol. It also assumes that you know how to program in Java.

Each example in this document first shows how to use the bare protocol to interact with Calendar, then shows how to use the Java client library to achieve the same effect. See the Java client library documentation for more information and more examples. If your client is written in another language, see the client library documentation for that language; it shouldn't be too hard to translate the examples in this document into other languages as needed.

Assume you're creating a website that needs to communicate with Google Calendar. You want your web pages to be able to get the feed from your calendar and add an event to your calendar. This section shows you how to do that, using either the HTTP-level protocol or the Google data API client library supplied by Google.

You can, of course, interact with your calendar in other ways too: update an event, delete an event, and so on. For more information and more example code that you can adapt for use with Calendar, see Using Google data APIs in Java.

Note: Items are updated and deleted using the HTTP verbs PUT and DELETE. These verbs are temporarily disallowed in the current version of Google Calendar. To work around this restriction, use an HTTP POST request instead, and include the appropriate method override header: X-HTTP-Method-Override: PUT or X-HTTP-Method-Override: DELETE. If you use the Java client library, you can tell it to automatically add the appropriate override headers by running your code with -Dcom.google.gdata.UseMethodOverride=true on the command line.

Note that the first few examples below assume that you're interacting with your own Calendar account. If you're writing a Calendar client application, your client will, of course, have to interact with a user's account. The later examples in this document show how to use authentication, which your client will need to do to interact with a user's account.

You'll probably want a Calendar account for testing purposes. To create a Calendar account, go to Google Calendar and log in using your Google account email and password. (If you don't have a Google account, click the "Create an account now" link.)

There are a variety of different URLs you can use to request feeds from a calendar; for more information, see Calendar feed types, later in this document.

The simplest feed URL to use is that of the calendar's read-only so-called "magic cookie" private feed, because that URL doesn't require authentication. The usual procedure for determining that URL involves using a JavaScript-enabled GUI browser to get the URL manually. If you can't or don't want to use such a browser, then you can instead interact with Calendar using one of the other feed URLs, which require authentication, but which you can construct without using a browser. Those URLs (and information on how to use authentication) are covered in later examples, but even if you aren't going to use the "magic cookie" URL, you should read through the first couple of examples to learn the basics of sending Calendar requests.

To find your calendar's "magic cookie" feed URL:

In the list of calendars on the left side of the page, find the calendar you want to interact with. You can create a new calendar for this purpose if you want to.

Click the arrow button to the right of the calendar. Select "Calendar settings" from the drop-down menu. The Calendar Details page appears.

Scroll down to the Private Address section. There are two buttons; select the XML button. The feed URL appears.

Copy the URL. This is the URL of your calendar's read-only "magic cookie" private feed; it includes a special coded string that lets you read the private feed without having to do authentication. This is the URL you'll use to request a feed from Calendar, so you won't have to do authentication just to view the feed.

The feed URL has the following form:

http://www.google.com/calendar/feeds/userID/private-magicCookie/basic

You can modify this URL in the following ways:

If you want a private feed that requires authentication, convert
the "private-{magic-cookie}" part of this path to just "private".

If you want the "full" calendar project, change the
last component
from "basic" to "full" in the URL. Using
"basic" returns a basic Atom feed without any extension
elements. Using "full" returns a feed that includes 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.

The "basic" form of the feed holds event information that is formatted
for reading, more suited to human consumption of the feed. The
"full" form of the feed holds structured events that are represented
as "Kinds", so they are more suited to computer processing.

If you're looking at settings for the user's main calendar, then userID is the user's email address. If you're looking at settings for another calendar, then userID is a longer and more complicated email address. In either case, magicCookie is a special code that lets you read the private feed without having to do authentication. Here's an example of a feed URL:

Under some circumstances, you may want to generate a new "magic cookie" URL. (Note that if someone else gets access to that URL, they can view your calendar without authentication.) To do that, click the "Reset Private URLs" link in the Calendar Details page.

The general idea of how to request a Calendar feed is that you determine the URL of the feed type you want (see Calendar feed types, later in this document), and then you send an HTTP GET request for that URL. Calendar then returns a GData feed containing calendar events, each of which is an Event kind. For more information about kinds, see the Kinds document.

Google provides client libraries for interacting with Google data API services in a variety of programming languages. You can use the client libraries to send the HTTP request and handle the returned feed; we'll show you an example of how to do that below. But whether or not you use the client library, the following is what's going on at the protocol level. If you're using a UNIX system and you want to try this out without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.

To get a feed, you send the following HTTP request to Calendar, using the URL you found in the previous section of this document:

GET http://www.google.com/calendar/feeds/userID/private-magicCookie/full

(With the appropriate values in place of userID and magicCookie, of course.)

When you send that GET request, Calendar returns an
HTTP 302 redirect; the redirect URL has a new query parameter,
gsessionid, appended to it. (Note that some methods of
sending the GET request may not show you the response
headers by default; if you receive a blank response, check your
HTTP utility's documentation to find out how to view response
headers.) That gsessionid parameter is the way that
Calendar keeps track of your session, to improve speed of
response.

(Some methods of sending the GET request may automatically follow redirects, in which case you don't need to send the second request described below.)

So after you've sent the GET request, you have to
read the HTTP headers of the response to find the URL with the
session ID appended; then you need to send another GET
request with that new URL. (Note that if you're using the UNIX
command line to send requests, you may have to precede the question
mark in the new URL with a backslash to keep your shell from
interpreting it.)

In response to the second GET request, Calendar returns an HTTP 200 OK status code and a feed containing all the events in your calendar. If there's only one event in your calendar, then Calendar returns something similar to the following feed. We've edited the following example a little to make it a little more readable by humans; in particular, a real Calendar feed contains actual magic-cookie values and entry IDs.

If your request fails for some reason, Calendar may return a different status code; for information about the status codes, see the Protocol document.

Note: The events in a feed are ordered by the values of their updated elements, with the most recently updated event appearing first in the feed.

View deleted events

There may be times you want to see cancelled events in a feed, such as when you want to synchronize your calendar between two calendar systems.
To see cancelled events, you must request a private authenticated
feed and specify an
updated-min query parameter.

Request the feed using the client library

The above description shows how to send a request and receive a response by hand. But we encourage you to instead use Google's client library where possible.

To use the client library, the general steps are:

Obtain or construct the appropriate URL.

Create an object of the CalendarService class, which handles communication and authentication with Calendar.

Use client library methods to send the request and receive any results the service sends back.

For example, to request the feed for your calendar, use the following Java code. You'll have to replace the URL in this example with the feed URL you obtained earlier.

URL feedUrl =
new URL("http://www.google.com/calendar/feeds/userID/private-magicCookie/full");
CalendarService myService = new CalendarService("exampleCo-exampleApp-1");
// Send the request and receive the response:
EventFeed myFeed = myService.getFeed(feedUrl, EventFeed.class);
// Print the title of the returned feed:
System.out.println(myFeed.getTitle().getPlainText());

In the above example, first you specify the URL, then you create a CalendarService object, then you call the getFeed method. That method handles all of the communication with Calendar—it sends the HTTP GET request, it receives the redirect, it sends the second GET request, it waits for the XML response to arrive, and it parses the XML and assigns the element contents and attribute values to appropriate parts of the Feed object.

If an error occurs during the getFeed call, then the client library generates an appropriate exception, so your code should be prepared to handle exceptions.

The final line of the above code calls the feed's getTitle method, which returns a TextConstruct object. To transform the text construct into a String, we call the title's getPlainText method.

In most contexts, you'll probably want to do something more with the feed than just print out the title. The client library lets you generate Atom or RSS representations of the feed and perform various other transformations. For more information, see the Javadoc documentation.

Adding an event to a calendar is a little bit more complicated than getting a feed, because you need to create the XML code or client-library object representing the event, and you need to use authentication.

Here's what you do at the protocol level:

First, create an entry of the Event kind. (For more information about kinds, see the Kinds document.) For example, you might create the following entry:

Then authenticate the user. To do that, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The POST body should contain a set of query parameters, as described in the following table. They should look like parameters passed by an HTML form, using the application/x-www-form-urlencoded content type.

Parameter

Description

Email

The user's email address.

Passwd

The user's password.

source

Identifies your client application. Should take the form companyName-applicationName-versionID; below, we'll use the name exampleCo-exampleApp-1.

If it succeeds, then the response from the service is an HTTP 200 OK status code, plus three long alphanumeric codes in the body of the response: SID, LSID, and Auth. The Auth value is the authorization token that you'll send to Calendar with your request, so keep a copy of that value. You can ignore the SID and LSID values.

Note that this authentication system (known as "Google Authentication for Installed Applications"; also known as "ClientLogin") is appropriate only for use in installed client applications such as desktop clients, not for use in web applications. For web applications, you should instead use the account authentication proxy, also known as "AuthSub". The AuthSub "scope" value for Google Calendar is "http://www.google.com/calendar/feeds". For more information about authentication, including detailed instructions for using AuthSub, see the Google Account Authentication documentation. The following instructions assume that you're using the ClientLogin system.

To post an entry, send the following HTTP request to Calendar, using a special "default" URL (and an Authorization header; see below). Calendar automatically redirects the default URL to the URL of the read/write private feed of the calendar belonging to the authenticated user. (Note that you don't have to use the default URL to send a POST request to Calendar; you can specify the user ID instead of "default" if you prefer. For more information, see the Feed Types section, later in this document.)

POST http://www.google.com/calendar/feeds/default/private/full

Before you send that request, you have to set the Authorization header in the request, using the following format:

Authorization: GoogleLogin auth=yourAuthToken

Where yourAuthToken is the Auth string returned by the login request.

The content that you send with the POST request
should be the <entry> element you created above,
using the application/atom+xml content type.

Just like in the previous example, Calendar returns an HTTP 302 redirect; the redirect URL has a new parameter, gsessionid, appended to it.

Finally, send the same POST request, with the same Authorization header and the same content, but with the gsessionid parameter appended.

When you send that second POST request, Calendar creates a calendar event, then returns an HTTP 201 CREATED status code, along with a copy of the new event in the form of an <entry> element. The returned entry is similar to the one you sent, but the returned one contains various elements added by Calendar, such as an <id> element.

If your request fails for some reason, Calendar may return a different status code; for information about the status codes, see the Protocol document.

Note that if you use GData to add an event to your calendar that involves multiple participants, the event appears on the other people's calendars just as it would if you added it by hand using the Calendar GUI.

Add an event using the client library

As an alternative to working with the raw HTTP and XML, you can post a new entry using the client library. To do that, you follow the same general steps as in the previous example, with a couple of extra steps mixed in:

Obtain or construct the appropriate URL. (In this case, the abovementioned "default" URL, for the read/write private feed of the authenticated user.)

Add the user's credentials to the CalendarService. (This document assumes that you're using the ClientLogin authentication system, for single-user installed desktop applications. If you're writing a web client and therefore want to use the AuthSub authentication system, see the document Using the Account Authentication Proxy with the GData Client Libraries.)

Use client library methods to send the request and receive any results the service sends back.

For example, to add an event to your calendar, use the following Java code. You'll have to replace the credentials in this example with the user's email address and password.

The above code creates a new entry of the Event kind, then sets various element values; then it creates a CalendarService, uses the setUserCredentials method to set the username and password, and calls the insert method to insert the entry and receive the response. If an error occurs during the insertion, then the client library generates an appropriate exception, so your code should be prepared to handle exceptions.

GData lets you request a set of entries that match specified criteria.
In addition to the standard GData query parameters, Calendar provides
two additional query parameters, start-min and start-max,
to let you request all events that fall within or overlap a range
of dates. For more information, see Calendar
query parameters reference.

It's a good idea to limit your queries to a range of dates if you're
not limiting them in any other way, just to avoid retrieving all entries ever posted to the calendar.

Here's how to create and send a date-range query at the protocol level:

First, authenticate the user, if you haven't already done so. See the previous example for information on how to do that.

Then send an HTTP request like the following to Calendar, using the special "default" URL:

GET http://www.google.com/calendar/feeds/default/private/full?start-min=2006-03-16T00:00:00&start-max=2006-03-24T23:59:59

Be sure to include the Authorization header in the request, as described in the previous example.

When you send that GET request, Calendar returns an HTTP 302 redirect with a gsessionid appended to it, just like in
the earlier examples. So read the HTTP headers of the response to find
the URL with the session ID appended; then send another
GET request with that new URL. (This second
GET request also needs to have the Authorization header
set.)

In response to the second GET request, Calendar returns
an HTTP 200 OK status code and a feed containing any
event that overlaps the minimum and maximum start times you specified.

To query using standard GData query parameters, just change the URL to use other parameters. (Note that Calendar doesn't support GData category queries.)

You can, of course, use the client library to send a query instead of sending it by hand. In this case, you'll need to add a new step to the process: constructing a CalendarQuery object, using client library methods.

For example, to view events on your calendar that overlap a particular
date range, use the following Java code. You'll have to replace
the credentials in this example with the user's email address and
password.

The above code creates a new CalendarQuery, which is a subclass of Query (the class corresponding to a standard GData query) that adds getters and setters for the start-min and start-max Calendar-specific query parameters. Then it sets the minimum and maximum start times; then it creates a CalendarService, uses the setUserCredentials method to set the username and password, and calls the query method to send the query and receive the response.

You can get a feed listing the calendars for a particular user by sending an authenticated GET request to the following URL:

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

Where userID is the user's email address.

The result is a "meta-feed," a feed that lists all of that user's calendars; each entry in the feed represents a calendar associated with the user. The list includes primary, secondary, and imported calendars, and all other calendars that the user has access to.

This feed is accessible only using an authentication token. You cannot use a “magicCookie” URL to access the feed. For information on authentication, see the earlier Add an event example.

To request the feed using the Java client library, you would use the same code that you might use to request any Calendar feed, except you give the meta-feed URL instead of an ordinary feed URL, and you have to be sure to declare the calendar feed extensions:

An extension profile defines what XML extensions are expected, where they appear, and the Java classes that should be used to parse them. The call to CalendarFeed().declareExtensions sets the CalendarService object's extension profile to recognize Calendar-specific extensions (see below). Note that this call declares all the defined extensions for both the <feed> and the <entry> elements, although in the current implementation there are no Calendar-specific extensions to <feed>.

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.

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

The URI of a representation of a Calendar feed takes the following form:

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

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

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

If you don't specify a projection or a visibility value, then the result is a feed that lists all of the user's calendars. For more information, see the Get a list of the user's calendars example, earlier.

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 Add an event, earlier in this document.

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:

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.

An event can have a subfeed of comments attached to it. 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:

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.

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.

In addition to the standard GData query parameters, Calendar uses the following parameters:

Parameter

Meaning

Notes

start-min

Earliest event start time to match. If not specified, default 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

Latest event start time to match. If not specified, default is 2031-01-01.

You can specify these two optional parameters to receive a feed
of events that overlap the specified time period—that
is, events that overlap start-min and start-max.

In fact, it's usually a good idea to specify at least one of these
parameters 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 peroid, 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 GData services, see the Common Elements ("Kinds") document.

Calendar does not support GData category queries. It does support full-text queries, using the standard GData q query parameter; it searches all of the text fields in events. It also supports the other standard GData query parameters. For more information about those parameters, see the Protocol 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.

In addition to the standard GData elements, Calendar uses the Contact, Event, and Message kinds described in the Kinds document.

Specifically, a Calendar feed contains entries that are Event kinds. Each event may contain <gd:who> elements that represent people associated with the event, each of whom is described with a Contact kind. Each event may also contain a <gd:comments> element that points to a feed containing Message kinds.

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 GData source of the calendar, if it came from a GData source.

atom:link[@rel='related']

Specifies a URL related to the feed.

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

Google Calendar provides several extension elements for use in a meta-feed (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.