CalDAV API Developer's Guide

CalDAV is an extension of WebDAV that provides a standard for clients to access calendar information on a remote server.

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:

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 API Console by creating a project.

Go to the Google API Console. Click Create project, enter a name, and click Create.

The next step is to activate CalDAV API.

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

  1. Open the API Library in the Google API Console. If prompted, select a project or create a new one. The API Library lists all available APIs, grouped by product family and popularity.
  2. If the API you want to enable isn't visible in the list, use search to find it.
  3. Select the API you want to enable, then click the Enable button.
  4. If prompted, enable billing.
  5. If prompted, accept the API's Terms of Service.
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. Select an existing OAuth 2.0 credential or open the Credentials page.
  2. If you haven't done so already, create your project's OAuth 2.0 credentials by clicking Create credentials > OAuth client ID, and providing the information needed to create the credentials.
  3. Look for the Client ID in the OAuth 2.0 client IDs section. For details, click the 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

The old endpoint https://www.google.com/calendar/dav is deprecated and no longer supported; use it at your own risk. We recommend you transition to the new endpoint format described above.