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:
- 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
.
- Does not support the
AUDIO
action.
- rfc5545: iCalendar
- Data exposed in the CalDAV interface is formatted according to the
iCalendar specification.
- Does not currently support
VTODO
or
VJOURNAL
data.
- Does not support the Apple iCal® extension to allow user-settable URL properties.
- rfc6578: Collection Synchronization for WebDAV
- Client applications must switch to this mode of operation after the
initial sync.
- 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.
- calendar-proxy: Calendar User Proxy Functionality in CalDAV
- To improve the performance of calendar synching from iOS devices, which
don't support delegation, using the
calendar-proxy-read-for
or
calendar-proxy-write-for
properties with an iOS UserAgent will fail.
We have not yet provided a full implementation of all of the relevant
specifications. However, for many clients such as Apple's Calendar app
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:
- 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.
- If the API you want to enable isn't visible in the list, use search to
find it.
- Select the API you want to enable, then click the
Enable
button.
- If prompted, enable billing.
- 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:
- Select an existing OAuth 2.0
credential
or open the
Credentials page
.
- 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.
- 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's Calendar app) 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 labeled
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.
iCal® is a trademark of Apple Inc.