Google Contacts API v2 Reference

Important: Versions 1 and 2 of the Google Contacts API have been officially deprecated as of April 20, 2012. They will continue to work as per our deprecation policy, but we encourage you to move to version 3.

This document provides detailed reference documentation for the raw protocol (XML and HTTP) for the Google Contacts Data API.

This document doesn't contain information about the programming-language client libraries. For client-library reference information, see the links from the programming-language-specific sections of the developer's guide.



This document is intended for programmers who want to write client applications that can interact with contacts.

It's a reference document; it assumes that you understand the concepts presented in the developer's guide, and the general ideas behind the Google Data APIs protocol.

Contacts feed types

The Contacts Data API provides two types of feed: contacts feed and contact groups feed.

The feeds are private read/write feeds that can be used to view and manage a user's contacts/groups. Since they are private, a programmer can access them only by using an authenticated request. That is, the request must contain an authentication token for the user whose contacts you want to retrieve. For more information about authenticating, see the developer's guide.

The representation of contact data depends on projection. Projection values indicate what data is included in the representation. For a list of values, see Projection values, below.

Contacts feed

The URL for a feed of contacts takes the following form:

To request a particular representation of a contacts feed, userID (e-mail address) and projection value have to be specified.

Default can also be used instead of the user's e-mail address (it tells the server to return the contact groups for the user whose credentials accompany the request).

For example, the contacts feed for a user and projection full would have the following URI:

Contact groups feed

Similarly to the contacts feed, the contact groups feed is specified by a userID (or default value) and projection:

Example: groups for a user with projection full can be obtained using the URL:

You can also substitute default for the user's email address, which tells the server to return the contact groups for the authenticated user whose credentials accompany the request.

Extended Properties and projections

Extended Properties

It is possible to set any additional contact- or contact group- related information as an exteded property (arbitrary name - value pair) for a contact or contact group entry. Preserving key uniqueness is a responsibility of clients. Value of the extended property may be stored as a value (arbitrary string) or an XML blob (these are mutually exclusive; instead of a valid XML blob plain text can be used). Each contact may have at most ten (10) extended properties associated. Each of them should be reasonably small, that is it should not be a photo, ringtone etc.


Extended property with a key and a value:

<gd:extendedProperty name="" value="some value"/>

Extended property with key and an XML blob:

<gd:extendedProperty name="">

To limit extended property visibility one can use projections: full, property-KEY or thin.

Projection values

Although the examples in this document use only the full projection, there are some other useful projections.

The following table describes the supported projection values:

Projection name Description
thin No gd:extendedProperty elements are returned/updated.
property-KEY KEY indicates the key of an extended property (gd:extendedProperty element) that will be returned (for GET) or should be updated (for PUT/POST). Absence of the extended property during update operation deletes the property.
full All gd:extendedProperty elements are returned and all of them have to be included during an update.

Contacts query parameters reference

The Contacts Data API supports the following standard Google Data API query parameters:

Name Description
alt The type of feed to return, such as atom (the default), rss, or json.
max-results The maximum number of entries to return. If you want to receive all of the contacts, rather than only the default maximum, you can specify a very large number for max-results.
start-index The 1-based index of the first result to be retrieved (for paging).
updated-min The lower bound on entry update dates.

For more information about the standard parameters, see the Google Data APIs protocol reference document.

In addition to the standard query parameters, the Contacts Data API supports the following parameters:

Name Description
orderby Sorting criterion. The only supported value is lastmodified.
showdeleted Include deleted contacts in the returned contacts feed. Deleted contacts are shown as entries that contain nothing but an <atom:id> element and a <gd:deleted> element. (Google retains placeholders for deleted contacts for 30 days after deletion; during that time, you can request the placeholders using the showdeleted query parameter.) Valid values are true or false.
sortorder Sorting order direction. Can be either ascending or descending.
group Constrains the results to only the contacts belonging to the group specified. Value of this parameter specifies group ID (see also: gContact:groupMembershipInfo).

Contacts elements reference

The Contacts Data API uses the standard Google Data API elements as well as elements specific for contacts.

In particular, a contact entry takes the form of an extended Contact kind, representing a person, a venue such as a club or a restaurant, or an organization. The Contact kind appears in XML as an <atom:entry> element that contains various extension elements from the Google Data namespace. For information about the standard Google Data API elements, see the Atom specification and the Kinds document.

The category element indicating that the entry is a contact looks like this:

<atom:category scheme=""

In the Contacts Data API, several elements are slightly more restrictive than indicated in the documentation for the Contact kind. In particular, a client must supply either a rel attribute or a label attribute, but not both, for the following elements:

  • gd:email
  • gd:im
  • gd:organization
  • gd:phoneNumber
  • gd:postalAddress

Caution: When you create or update a contact, if you supply both rel and label (or neither) for any of those elements, then the server rejects the entry.

However, the Contacts API allows arbritary string values for the protocol attribute of the gd:im element.

<gd:im protocol="MyProtocol" address="" rel="" primary="true"/>


Contact entry uses an extended gd:extendedProperty, which stores client-specific properties (see: Extended properties and projections).

An example of an entry with extended properties (with a full projection):

<entry gd:etag='"Q3k4cTVSLyp7ImA9WxRXFkwJRAA."'>
  <category scheme=''
    term='' />
  <content type='text'>Notes</content>
  <link rel='' type='image/*'
    href='' />
  <link rel='self' type='application/atom+xml'
    href='' />
  <link rel='edit' type='application/atom+xml'
    href='' />
  <gd:phoneNumber rel=''
  <gd:extendedProperty name='my-service-id' value='1234567890' />
  <gd:extendedProperty name='my-second-service'>
    <value-element>text value</value-element>

Important: Setting extended properties is allowed only within full or property-NAME projection.

Photos support

An <atom:link> element with rel="" provides a URL (in its href attribute) for adding, retrieving, updating, or deleting a contact's photo.

The photo link element appears for every contact, whether or not the contact has a photo. If a contact does not have a photo, then the photo link element has no gd:etag attribute.

Example photo link element, with ETag:

<link rel='' type='image/*'

Note: When using photo links, an authorization token in HTTP header has to be specified. For more details please take a look at: Authenticating.

gContact namespace

XML namespace URL for gContact:

In this namespace, an element is defined that represents a group to which the contact belongs.



Property Description
href Identifies the group to which the contact belongs or belonged. The group is referenced by its id.
deleted="true"? Means, that the group membership was removed for the contact. This attribute will only be included if showdeleted is specified as query parameter, otherwise groupMembershipInfo for groups a contact does not belong to anymore is simply not returned.


Contact was deleted from the group and is in group

<gContact:groupMembershipInfo href="" deleted="true"/>
<gContact:groupMembershipInfo href=""/>

Contact groups elements reference


contactGroup = element atom:entry {
     element gd:deleted?,
     element gd:extendedProperty*,

The table below details contact groups schema:

Element Property Description
entry atom:category Scheme:
  atom:updated The modification time for a group is greater than or equal to the time the user actually modified the item. Applications should not use the modification time to break ties.
  atom:title Group's name.
  atom:content Group's name. Not directly updatable; changes whenever the name of the group is updated via atom:title.
  gd:deleted If present, denotes, that the group was deleted.
  gd:extendedProperty* Stores client-specific properties. There are client-specific projections created, that support independent read/modify on the properties.
  gContact:systemGroup? If present, indicates the group is a system one.
gContact:systemGroup id System group id, an identifier that allows to distinguish various system groups.

There is a limited set of possible values for the id attribute of the gContact:systemGroup element. These values are enumerated in the table below:

System group id Meaning
"Contacts" The My Contacts system group.
"Friends" The Friends system group.
"Family" The Family system group.
"Coworkers" The Coworkers system group.

An example of a non-system contact group entry:

<entry xmlns=""
    <category scheme=""
    <app:edited xmlns:app="">2006-01-01T00:00:00Z</app:edited>
    <title>Salsa class members</title>
    <link rel="self" type="application/atom+xml"
    <link rel="edit" type="application/atom+xml"
    <gd:extendedProperty name="more info">
        <description>A group that gathers salsa members.</description>

An example of a contact group entry for a system group:

<entry xmlns=""
    <category scheme=""
    <title>System Group: My Contacts</title>
    <content>System Group: My Contacts</content>
    <link rel="self" type="application/atom+xml"
    <gContact:systemGroup id="Contacts"/>

Contact groups query parameters reference

Using the feed for contact groups one can use all of the query parameters available for the contact feed (see: Contacts query parameters reference) except for the group parameter.

Contacts Feeds Schema Reference

  1. Contacts Feed
  2. Contact Groups Feed