You can view and manage your contacts using Google's CardDAV protocol.
Contacts are stored in the user's Google Account; most Google services have access to the contact list. Your client application can use the CardDAV API to create new contacts, edit or delete existing contacts, and query for contacts that match particular criteria.
Specifications
The full specification is not implemented, but many clients such as Apple iOS™ Contacts and macOS should interoperate correctly.
For each relevant specification, Google's CardDAV support is as follows:
- rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)
- Supports the HTTP methods
GET
,PUT
,DELETE
,OPTIONS
, andPROPFIND
. - Does not support the HTTP methods
LOCK
,UNLOCK
,COPY
,MOVE
, orMKCOL
. - Does not support arbitrary (user-defined) WebDAV properties.
- Does not support WebDAV Access Control (rfc3744).
- Supports the HTTP methods
- rfc5995: Using POST to Add Members to WebDAV Collections
- Supports creating new contacts without specifying an ID.
- rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and
Versioning (WebDAV)
- Supports the HTTP method
REPORT
, but not all defined reports are implemented. - Supports providing a principal collection and a contacts collection.
- Supports the HTTP method
- rfc6578: Collection Synchronization for WebDAV
- Client applications must switch to this mode of operation after the initial sync.
- rfc6749: The OAuth 2.0 Authorization Framework and
rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage
- Supports authenticating CardDAV client programs using OAuth 2.0 HTTP Authentication. Google does not support any other authentication method. For security of contact data, we require CardDAV connections to use HTTPS.
- rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)
- Bootstrapping of CardDAV URLs must take place according to section 6 of rfc6764.
- Supports
caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV,
which is shared between the CardDAV and CalDAV specifications. The contacts
ctag
is like a resourceETag
; it changes when anything in the contact address book has changed. This allows the client program to quickly determine that it does not need to synchronize any changed contacts. - Google uses VCard 3.0 as the contact encoding format. See: rfc6350: VCard 3.0.
Google’s CardDAV requires OAuth 2.0
Google’s CardDAV interface requires OAuth 2.0. Refer to the linked documentation below for information on using OAuth 2.0 to access Google APIs:
Connecting to Google's CardDAV server
The CardDAV protocol allows discovery of the address book and contact resources URIs. You must not hardcode any URI as they could change at any time.
Client applications must use HTTPS, and OAuth 2.0
authentication must be
provided for the user's Google account. The CardDAV server will not
authenticate a request unless it arrives over HTTPS with OAuth 2.0
authentication of a Google account, and your application is registered on
DevConsole. Any attempt to connect over HTTP with Basic authentication or with
an email/password that doesn't match a Google account results in an HTTP
401 Unauthorized
response code.
To use CardDAV, your client program must initially connect to the canonical
discovery path by performing an HTTP PROPFIND
on:
https://www.googleapis.com/.well-known/carddav
Once redirected (HTTP 301
) to an Address Book Resource, your client program
can then perform a PROPFIND
on it to discover the
DAV:current-user-principal
, DAV:principal-URL
, and addressbook-home-set
properties. Your client program can then discover the principal address book by
performing a PROPFIND
on the addressbook-home-set
and looking for the
addressbook
and collection
resources. A full description of this process
is beyond the scope of this document. See
rfc6352 for more details.
The redirect path returned in the HTTP 301
response through a PROPFIND
on
the well-known URI must not be permanently cached (as per
rfc6764). Devices should retry well-known
URI discovery periodically to verify if the cached path is still up to date and
resync if the path ever changes. Google recommends a rate of every 2-4 weeks.
Resources
CardDAV uses REST concepts. Client applications act on resources that are designated by their URIs. The current URI structure is specified here to help developers understand the concepts in the following section. The structure may change and must not be hardcoded. Rather, the resources should be discovered according to the RFC.
- Principal
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Home Set
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- Address Book
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- Contact
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
Synchronizing Contacts
The following is a general description of the operations supported. Developers should look for the details in the relevant RFC. Requests and responses are mostly encoded in XML. These are the main operations used by client applications for synchronization:
- Using CTag
- Client programs use the
getctag
PROPFIND
request on the Address Book resource to determine if any contact has changed on the server and therefore whether a synchronization is needed. The value of this property is guaranteed to change if any contact changes. Client applications should store this value and use it only on the initial sync and as a fallback when async-token
is invalidated. Periodically polling for thegetctag
property will result in throttling.
- Client programs use the
- Using sync-token
- Client programs use the
sync-token
PROPFIND
request on the Address Book to obtain thesync-token
representing its current state. Client applications must store this value and issue periodicsync-collection
REPORT
requests to determine changes since the last issuedsync-token
. Issued tokens are valid for 29 days, and theREPORT
response will contain a newsync-token
.
- Client programs use the
- Using ETags
- Client applications issue a
getetag
PROPFIND
request on the Address Book resource (withDEPTH
header equal toDEPTH_1
). By maintaining theETag
value of each contact, a client program can request the value of contacts that had theirETag
changed.
- Client applications issue a
- Retrieving contacts
- Client applications retrieve contacts by issuing an
addressbook-multiget
REPORT
request. Given a list of contact URIs, the report returns all the requested contacts as VCard 3.0 values. Each entry includes anETag
for the contact.
- Client applications retrieve contacts by issuing an
- Inserting a contact
- Client applications issue a
POST
request with the new contact in VCard 3.0 format. The response will contain the ID of the new contact.
- Client applications issue a
- Updating a contact
- Client applications issue a
PUT
request with the updated contact in VCard 3.0 format. The contact is updated if the contact already exists in the address book. - Client applications should include an
If-Match
header with the contact's currently knownETag
. The server will then reject thePUT
request (withHTTP 412
) if the currentETag
on the server is different from theETag
sent by the client program. This allows for optimistic serialization of updates.
- Client applications issue a
- Deleting a contact
- Client applications delete a contact by issuing a
DELETE
request against the contact URI.
- Client applications delete a contact by issuing a