English | Site Directory

Google Calendar APIs and Tools

Frequently Asked Questions

Main Google Data FAQ

The questions below are specifically targeted for the Calendar Data API. There are, however, many questions that are applicable to all of the Data APIs. Visit the Google Data APIs FAQ if you do not find the question you are looking for below.

    Getting Started

  1. How do I install and use the .NET Client Library?
  2. Where do I find the Developer's Guide for the Calendar data API?
  3. How can I add my Google Calendar to my web site?
  4. Can I use the Calendar data API from my favorite programming language?
  5. What functionality is available through the Calendar Data API?
  6. Where do I find the Help Center for the Google Calendar web interface?
  7. Is the Calendar data API based upon any standard formats or protocols?
  8. Where can I go to get help with a problem I'm experiencing?

    9. Using the Calendar Data API

  9. What are web content events?
  10. How do I publish web content events?
  11. How do I add comments to an event?
  12. Can I create and delete calendars via the API?
  13. How do I retrieve more than 25 results in an event feed?
  14. How do I add an all-day event?
  15. How do I mark attendees as accepted when I add an event?
  16. How do I send notifications to invitees of events I create through the API?
  17. How do I change the order of events in the feed?
  18. How do I add an exception to a recurring event?
  19. Events that have already occurred are appearing in the feed. How do I get a feed with only future events?
  20. Can I add custom name/value pairs to events?
  21. How do I delete an "extendedProperty" element?

    22. Known Calendar Data API Issues

  22. Why do I sometimes get a 400 response when posting a recurring event?
  23. I have defined a custom TZID in a recurring event, but the server fails to process the recurrence rule. Why?
  24. Why can't I authenticate to Google Calendar using a single use (non-session) AuthSub token?
  25. Why do I get a 404 error when updating an event?
  26. I receive a 400 response when trying to update a single event with a "gd:recurrence" element. Why?
  27. Why am I getting a DEADLINE_EXCEEDED error?
  28. How do I delete an "extendedProperty" element?

Getting Started

How do I install and use the .NET Client Library?
You can find more information in the Getting Started article for .NET:
http://code.google.com/apis/gdata/articles/dotnet_client_lib.html
Where do I find the Developer's Guide for the Calendar data API?
The Developer's Guide contains information on both the protocol used by the API as well as language-specific examples for performing the major operations in several of the GData client libraries.
How can I add my Google Calendar to my web site?
There are several options available:
  • You can embed your calendar using some simple HTML.
  • You can use the JSON output from the API to display your events using client-side JavaScript. There are code samples available to help you.
  • You can use your favorite programming language to call the API directly from your server-side code. We do provide client libraries for some popular languages.
Can I use the Calendar data API from my favorite programming language?

Because the Calendar data API is XML-based, you can use the API from nearly any programming language. Most languages have libraries for handling HTTP and XML, though this functionality isn't strictly necessary so long as you have some networking libraries and can manipulate streams and strings.

To simplify the use of our APIs, we provide several client libraries for some popular languages.

Download client libraries at the following URLs:

Our partner, Zend, has a PHP client library as part of the Zend Framework: PHP

What functionality is available through the Calendar Data API?
Much of the functionality available through the Calendar Web UI is also made available via the API. Feeds of events can be retrieved in either Atom or RSS formats. In addition to retrieval, you can also add, update, and delete calendar events as well. Separate event comment feeds are also available. You cannot currently add or delete calendars through the API.
Where do I find the Help Center for the Google Calendar web interface?
Google Calendar has a Help Center dedicated to the web interface.

In general, functionality not available through the Google Calendar web interface is also not available through the API. However, you're welcome to post API feature requests to the Calendar data API discussion group.

Is the Calendar data API based upon any standard formats or protocols?
Yes! The GData protocol (and thus the Calendar data API) is based on Atom, RSS and the Atom Publishing Protocol (APP). The API also takes advantage of extension mechanisms in these protocols to implement additional functionality such as a query language and an authentication system.
Where can I go to get help with a problem I'm experiencing?
If you can't find a solution in this knowledge base or the documentation, you're welcome to post your question to the discussion group. Members of the developer community, including some Googlers, actively read and respond to questions posed in the group.

Using the Calendar Data API

What are web content events?

Web Content events can be published either as an iCalendar file or via the Calendar data API.


Publishing via the Calendar data API:

A typical ATOM entry that represents a standard all-day event might look something like this:

<entry>
⋮
<title type="text">Independence Day</title>
<gd:when startTime="2006-07-04" endTime="2006-07-05" />
⋮
</entry>


This would create an event called "Independence Day" on July 4th. If you wanted to add web content to this event, you could change it as follows (added fields are in green boldface):

<entry>
⋮
<title type="text">No work today!</title>
<gd:when startTime="2006-07-04" endTime="2006-07-05" /> 

<atom:link rel="http://schemas.google.com/gCal/2005/webContent"
               title="Independence Day"
               href="http://www.google.com/calendar/images/google-holiday.gif" 
               type="image/gif">
       <gCal:webContent url="http://www.google.com/logos/july4th06.gif"
                        width="276"
                        height="120" />
    </atom:link>
⋮
</entry>


These fields tell Google Calendar to display this event specially and where to find the additional web content associated with the event. The details for each of these fields is described below. You can set these fields using the Google Calendar data API.


  • <atom:link rel="http://schemas.google.com/gCal/2005/webContent"
    • title (required): Specifies the title of the event that appears in the header of the pop-up window and the tooltip that appears when hovering over the icon.
    • href (required): Specifies the icon that should be displayed at the top of each day. Icons may be in any image format that can be displayed in a web browser. The image will be scaled to display at 16x16.
    • type: Specifies the type of the content. Allowed values include text/html or image/*. This field is required if a CONTENT-URL is specified. If text/html is used, the content will be displayed in an IFRAME; if image/* is used, the content will be displayed in an IMG element.
  • <gCal:webContent
    • url: A link to the content to display in the pop-up window. You can link to an HTML file or image as long as you properly set the type attribute above.
    • width: Specifies the width (in pixels) of the IFRAME or IMG element.
    • height: Specifies the height (in pixels) of the IFRAME or IMG element.


Publishing using an iCalendar file:

A typical iCalendar file that represents a standard all-day event might look something like this:

BEGIN:VEVENT
DTSTART;VALUE=DATE:20060704
DTEND;VALUE=DATE:20060705
SUMMARY:Independence Day
END:VEVENT

This would create an all-day event called "Independence Day" on July 4.

If you wanted to add web content to this event, you just need to add a few additional fields to the event description in iCalendar (the added fields are in green boldface):

BEGIN:VEVENT
DTSTART;VALUE=DATE:20060704
DTEND;VALUE=DATE:20060705
SUMMARY:Independence Day
X-GOOGLE-CALENDAR-CONTENT-TITLE:Independence Day
X-GOOGLE-CALENDAR-CONTENT-ICON:http://www.google.com/calendar/images/google-holiday.gif
X-GOOGLE-CALENDAR-CONTENT-URL:http://www.google.com/logos/july4th06.gif
X-GOOGLE-CALENDAR-CONTENT-TYPE:image/gif
X-GOOGLE-CALENDAR-CONTENT-WIDTH:276
X-GOOGLE-CALENDAR-CONTENT-HEIGHT:120
END:VEVENT


These fields tell Google Calendar to display this event specially and where to find the additional web content associated with the event. The details for each of these fields are described below:

  • X-GOOGLE-CALENDAR-CONTENT-TITLE (required): Specifies the title of the event that appears in the header of the pop-up window and the tooltip that appears when hovering over the icon.
  • X-GOOGLE-CALENDAR-CONTENT-ICON (required): Specifies the icon that should be displayed at the top of each day. Icons may be in any image format that can be displayed in a web browser. The image will be scaled to display at 16x16.
  • X-GOOGLE-CALENDAR-CONTENT-URL: A link to the content to display in the pop-up window. You can link to an HTML file or image, as long as you properly set X-GOOGLE-CALENDAR-CONTENT-TYPE.
  • X-GOOGLE-CALENDAR-CONTENT-TYPE: Specifies the type of the content. Allowed values include text/html or image/*. This field is required if a CONTENT-URL is specified. If text/html is used, then the content will be displayed in an IFRAME; if image/* is used, then the content will be displayed in an IMG element.
  • X-GOOGLE-CALENDAR-CONTENT-WIDTH: Specifies the width (in pixels) of the IFRAME or IMG element.
  • X-GOOGLE-CALENDAR-CONTENT-HEIGHT: Specifies the height (in pixels) of the IFRAME or IMG element.
How do I publish web content events?

Web Content events can be published either as an iCalendar file or via the Calendar data API.


Publishing via the Calendar data API:

A typical ATOM entry that represents a standard all-day event might look something like this:

<entry>
⋮
<title type="text">Independence Day</title>
<gd:when startTime="2006-07-04" endTime="2006-07-05" />
⋮
</entry>


This would create an event called "Independence Day" on July 4th. If you wanted to add web content to this event, you could change it as follows (added fields are in green boldface):

<entry>
⋮
<title type="text">No work today!</title>
<gd:when startTime="2006-07-04" endTime="2006-07-05" /> 

<atom:link rel="http://schemas.google.com/gCal/2005/webContent"
               title="Independence Day"
               href="http://www.google.com/calendar/images/google-holiday.gif" 
               type="image/gif">
       <gCal:webContent url="http://www.google.com/logos/july4th06.gif"
                        width="276"
                        height="120" />
    </atom:link>
⋮
</entry>


These fields tell Google Calendar to display this event specially and where to find the additional web content associated with the event. The details for each of these fields is described below. You can set these fields using the Google Calendar data API.


  • <atom:link rel="http://schemas.google.com/gCal/2005/webContent"
    • title (required): Specifies the title of the event that appears in the header of the pop-up window and the tooltip that appears when hovering over the icon.
    • href (required): Specifies the icon that should be displayed at the top of each day. Icons may be in any image format that can be displayed in a web browser. The image will be scaled to display at 16x16.
    • type: Specifies the type of the content. Allowed values include text/html or image/*. This field is required if a CONTENT-URL is specified. If text/html is used, the content will be displayed in an IFRAME; if image/* is used, the content will be displayed in an IMG element.
  • <gCal:webContent
    • url: A link to the content to display in the pop-up window. You can link to an HTML file or image as long as you properly set the type attribute above.
    • width: Specifies the width (in pixels) of the IFRAME or IMG element.
    • height: Specifies the height (in pixels) of the IFRAME or IMG element.


Publishing using an iCalendar file:

A typical iCalendar file that represents a standard all-day event might look something like this:

BEGIN:VEVENT
DTSTART;VALUE=DATE:20060704
DTEND;VALUE=DATE:20060705
SUMMARY:Independence Day
END:VEVENT

This would create an all-day event called "Independence Day" on July 4.

If you wanted to add web content to this event, you just need to add a few additional fields to the event description in iCalendar (the added fields are in green boldface):

BEGIN:VEVENT
DTSTART;VALUE=DATE:20060704
DTEND;VALUE=DATE:20060705
SUMMARY:Independence Day
X-GOOGLE-CALENDAR-CONTENT-TITLE:Independence Day
X-GOOGLE-CALENDAR-CONTENT-ICON:http://www.google.com/calendar/images/google-holiday.gif
X-GOOGLE-CALENDAR-CONTENT-URL:http://www.google.com/logos/july4th06.gif
X-GOOGLE-CALENDAR-CONTENT-TYPE:image/gif
X-GOOGLE-CALENDAR-CONTENT-WIDTH:276
X-GOOGLE-CALENDAR-CONTENT-HEIGHT:120
END:VEVENT


These fields tell Google Calendar to display this event specially and where to find the additional web content associated with the event. The details for each of these fields are described below:

  • X-GOOGLE-CALENDAR-CONTENT-TITLE (required): Specifies the title of the event that appears in the header of the pop-up window and the tooltip that appears when hovering over the icon.
  • X-GOOGLE-CALENDAR-CONTENT-ICON (required): Specifies the icon that should be displayed at the top of each day. Icons may be in any image format that can be displayed in a web browser. The image will be scaled to display at 16x16.
  • X-GOOGLE-CALENDAR-CONTENT-URL: A link to the content to display in the pop-up window. You can link to an HTML file or image, as long as you properly set X-GOOGLE-CALENDAR-CONTENT-TYPE.
  • X-GOOGLE-CALENDAR-CONTENT-TYPE: Specifies the type of the content. Allowed values include text/html or image/*. This field is required if a CONTENT-URL is specified. If text/html is used, then the content will be displayed in an IFRAME; if image/* is used, then the content will be displayed in an IMG element.
  • X-GOOGLE-CALENDAR-CONTENT-WIDTH: Specifies the width (in pixels) of the IFRAME or IMG element.
  • X-GOOGLE-CALENDAR-CONTENT-HEIGHT: Specifies the height (in pixels) of the IFRAME or IMG element.

How do I add comments to an event?
Adding comments to an event is done by POST ing a new entry element to the comments feed. The comments feed location can be found in a gd:comments element inside the event entry. Please see the documentation on gd:comments for more information. A calendar event's comments feed location is typically the ID of the event with /comments appended.
Can I create and delete calendars via the API?

To create a calendar - http://code.google.com/apis/calendar/developers_guide_protocol.html#CreatingCalendars

To delete a calendar - http://code.google.com/apis/calendar/developers_guide_protocol.html#DeletingCalendars

How do I retrieve more than 25 results in an event feed?

You can use the query parameter max-results to retrieve more than the default 25. If you wish to retrieve all of the events in a feed, set the max-results parameter to a really large number. You can also page through events by taking advantage of the next links, available as child elements of a feed.

How do I add an all-day event?

All-day events are created using a gd:when/@startTime value representing the date on which the event will take place. As the gd:when/@endTime value is exclusive, it should be set to the day after the event.

For instance, to create an all day event on the 5th of January, 2008, you would set the when element to this:

<gd:when startTime="2008-01-05" endTime="2008-01-06"/>

You can choose to omit the endTime attribute and the server will correctly insert the event. However, the endTime will exist in the entry returned from the server.

For more information on the use of dates and times when working with single events, please see the Event "kind" documentation.

How do I mark attendees as accepted when I add an event?

This can be done by including the gd:attendeeStatus element as a child of a gd:who element. Please see the documentation on gd:who

How do I send notifications to invitees of events I create through the API?

Notifications are controlled by a boolean element called gCal:sendEventNotifications . To enable notifications, add this element as a child of the atom:entry element: <gCal:sendEventNotifications xmlns:gCal="http://schemas.google.com/gCal/2005" value="true"/>

How do I change the order of events in the feed?

By default, entries are ordered based upon the last update time of the entry. You can choose to sort events by occurrence time by specifying orderby=starttime as a query parameter. Sorting can also be set as being in ascending or descending order using the query parameter sortorder=(ascending|descending) . The client libraries we provide contain functions to handle building the query strings for a feed.

An example URL for retrieving the next 10 events on the calendar of the authenticated user in ascending order is:

http://www.google.com/calendar/feeds/default/private/full?futureevents=true&orderby=starttime&sortorder=ascending&max-results=10

How do I add an exception to a recurring event?

Exceptions to recurring events are created by POST ing a new entry containing a gd:originalEvent element referencing the startTime of the recurring event being modified. Updates to the properties of an event can be made, or the event can be canceled by changing the status of the event in the POSTed entry.

Events that have already occurred are appearing in the feed. How do I get a feed with only future events?
Use the query parameter futureevents=true when requesting the feed. Client libraries also have some functions to handle building the query strings for a feed.
Can I add custom name/value pairs to events?

Yes, there is support through this element: which can be added as a child to an entry. Corresponding ExtendedProperty classes also exist in the .NET and Java client libraries to assist you with these elements. Currently, extendedProperty elements cannot be deleted via the API or searched using the q= parameter.

The name attribute value can be up to 45 characters, and the maximum character length for value is 1024.

How do I delete an "extendedProperty" element?

There is currently no way to delete an extended property.

Known Calendar Data API Issues

Why do I sometimes get a 400 response when posting a recurring event?

There is an intermittent issue which is causing a 400 response when processing some gd:recurrence elements. The body of the response will be "Failed to process recurrence rule". Please try the request again.

I have defined a custom TZID in a recurring event, but the server fails to process the recurrence rule. Why?

Custom time zone definitions in recurring events do not currently work. Please use a standard Java time zone ID.

Why can't I authenticate to Google Calendar using a single use (non-session) AuthSub token?

One-time-use tokens are not currently supported with Calendar. Please exchange it for a session token instead.

Why do I get a 404 error when updating an event?

A 404 error is currently returned if you are missing the proper xmlns namespace declarations on the entry. Please make sure you are specifying this correctly in your update.

I receive a 400 response when trying to update a single event with a "gd:recurrence" element. Why?

A 400 response with a message "Single event must not have a recurrence rule" is currently returned when trying to change a non-recurring event into one with a recurrence rule.

Why am I getting a DEADLINE_EXCEEDED error?

This error is caused by a communication failure on the server side. This error is returned in a HTTP message with a 500 status code, indicating that the problem was on the server rather than in the data you sent. If you get this error you should resend your request.

How do I delete an "extendedProperty" element?

There is currently no way to delete an extended property.