English | Site Directory

Contacts Data API

Reference Guide

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.

Contents

  1. Audience
  2. Contacts feed types
  3. Contacts query parameters reference
  4. Contacts elements reference

Audience

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 a single type of feed: the contact feed.

A contact feed is a private read/write feed that can be used to view and manage a user's contacts. The URI for the feed is as follows:

http://www.google.com/m8/feeds/contacts/userID/base

For example, the contacts feed for user liz@gmail.com would have the following URI:

http://www.google.com/m8/feeds/contacts/liz%40gmail.com/base

Since the contact feed is private, you can access it 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.

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.

Contacts elements reference

The Contacts Data API uses the standard Google Data API elements.

In particular, a contact entry takes the form of a 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="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/contact/2008#contact"/>

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

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.