Google Apps Platform

CalDAV API Developer's Guide

The endpoint https://www.google.com/calendar/dav is deprecated and no longer supported, use it at your own risk. Please make sure you transition to the new endpoint.

Google provides a CalDAV interface that you can use to view and manage calendars using the CalDAV protocol.

Specifications

For each of the relevant specifications, Google's CalDAV support is as follows:

  • rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)
    • Supports the HTTP methods GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND and PROPPATCH.
    • Does not support the HTTP methods LOCK, UNLOCK, COPY, MOVE, or MKCOL, or the If* header (except for If-Match).
    • Does not support arbitrary (user-defined) WebDAV properties.
    • Does not support WebDAV Access Control (rfc3744).
  • rfc4791: Calendaring Extensions to WebDAV (CalDAV)
    • Supports the HTTP method REPORT. All reports except free-busy-query are implemented.
    • Does not support the HTTP method MKCALENDAR.
  • rfc5545: iCalendar
    • Data exposed in the CalDAV interface are formatted according to the iCalendar specification.
    • Does not currently support VTODO or VJOURNAL data.
  • rfc6638: Scheduling Extensions to CalDAV
    • Supports a trivial "inbox," which is always empty.
    • Invitations you receive are automatically delivered into your "events" collection rather than being placed into your "inbox."
    • Does not support free-busy lookup.
  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV
    • The calendar ctag is like a resource etag; it changes when anything in the calendar has changed. This allows the client application to quickly determine that it does not need to synchronize any changed events.

We have not yet provided a full implementation of all of the relevant specifications, however for many clients such as Apple iCal™ the CalDAV protocol should interoperate correctly.

Note: For account security and to prevent abuse, Google might set cookies on client applications that access data via CalDAV.

Creating your client ID

To use the CalDAV API you need to have a Google Account. If you already have an account you can use, then you're all set.

Before you can send requests to the CalDAV API, you must register your client with the Google Developers Console by creating a project.

Visit the Google Developers Console and select Create Project. Enter a name and a project ID, or accept the defaults, and select Create.

The next step is to activate CalDAV API.

To activate an API for your project, do the following:

  1. Go to the Google Developers Console.
  2. Select a project.
  3. In the sidebar on the left, select APIs & auth.
  4. In the displayed list of available APIs, find the one you want to activate, and set its status to ON.
To perform CalDAV API requests you will need Client ID and Client Secret.

To find your project's client ID and client secret, do the following:

  1. Go to the Google Developers Console.
  2. Select a project.
  3. In the sidebar on the left, select APIs & auth. In the displayed list of APIs, make sure all the APIs you are using show a status of ON.
  4. In the sidebar on the left, select Credentials.
  5. Find the lines labeled Client ID and Client secret. Note that there may be a client ID without a client secret, for use with Compute Engine and App Engine; in that case, create a new client ID and client secret by selecting Create New Client ID.

Connecting to Google's CalDAV server

To use the CalDAV interface, a client program initially connects with the calendar server at one of two starting points. In either case, the connection must be made over HTTPS and must use the OAuth 2.0 authentication scheme. The CalDAV server will refuse to authenticate a request unless it arrives over HTTPS with OAuth 2.0 authentication of a Google account. Attempting to connect over HTTP or using Basic Authentication results in an HTTP 401 Unauthorized status code.

If the client program (such as Apple iCal) requires a principal collection as the starting point, the URI to connect to is:

https://apidata.googleusercontent.com/caldav/v2/calid/user

Where calid should be replaced by the "calendar ID" of the calendar to be accessed. This can be found through the Google Calendar web interface as follows: in the pull-down menu next to the calendar name, select Calendar Settings. On the resulting page the calendar ID is shown in a section labelled Calendar Address. The calendar ID for a user's primary calendar is the same as that user's email address.

If a client program (such as Mozilla Sunbird) requires a calendar collection as the starting point, the URI to connect to is:

https://apidata.googleusercontent.com/caldav/v2/calid/events

Contact us

You can report new bugs and feature requests on our CalDAV developer forum. Before you contact us, please, review the existing issues.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.