Admin SDK

Google Domain Shared Contacts API

The Shared Contacts API allows client applications to retrieve and update external contacts that are shared to all users in a Google Apps domain. Shared contacts are visible to all users of an Apps domain and all Google services have access to the contact list. To retrieve and update Google Apps domain users contact information use the Profiles API instead.

Your client application can use the Shared Contacts API to create new shared contacts, edit or delete existing shared contacts, and query for shared contacts that match particular criteria.

In addition to providing some background on the capabilities of the Shared Contacts API, this document provides examples of how to manipulate contacts using XML and HTTP. After reading this document, you may wish to learn more about interacting with the API using our client libraries by reading the programming-language specific sections of this developer's guide.

Contents

Overview

This version of the Shared Contacts API follows the principles of the Google Data APIs. Google Data APIs are based on both the Atom 1.0 and RSS 2.0 syndication formats in addition to the Atom Publishing Protocol.

Note: The Domain Shared Contacts API is only available to Google Apps for Business and Education accounts. To enable the API, log in to your admin account, and click the User accounts tab. Then click the Settings subtab, select the checkbox to enable the Provisioning API and save your changes. Please note changes can take up to 24 hours to be reflected in the email address auto-complete and the contact manager.

Audience

This document is intended for programmers who want to write client applications that can manipulate Google's contact lists using HTTP and XML.

This document assumes that you understand the general ideas behind the Google Data APIs protocol.

If you're using a UNIX system and you want to try the examples in this document without writing any code, you may find the UNIX command-line utilities curl or wget useful, as well as detailed instructions on using cURL with Google Data services.

Getting started

Before using the Shared Contacts API, you will need an administrator username and password for your Google Apps domain.

Authenticating

All Domain Shared Contacts API feeds are private. Thus, your client needs to authenticate before accessing a contacts feed. Desktop clients should use ClientLogin username/password or username/access code authentication; Web clients should use AuthSub or OAuth proxy authentication.

For more information about authentication with Google Data APIs in general, see the authentication documentation.

AuthSub proxy authentication

AuthSub proxy authentication is used by web applications that need to authenticate their users to Google Accounts. The website operator and the client code don't have access to the username and password for the user; instead, the client obtains special AuthSub tokens that allow the client to act on a particular user's behalf. For more detailed information, see the AuthSub documentation.

When a user first visits your application, they have not yet been authenticated. In this case, you need to display some information and a link directing the user to a Google page to authenticate your request for access to their contacts.

The following query parameters are included in the AuthSubRequest URL:

Parameter Description
next The URL of the page that Google should redirect the user to after authentication.
hd The hosted domain account to be accessed.
scope Indicates that the application is requesting a token to access contacts feeds. The scope string to use is http://www.google.com/m8/feeds/ (URL-encoded).
secure Indicates whether the client is requesting a secure token.
session Indicates whether the token returned can be exchanged for a multi-use (session) token.

If you aren't requesting a secure token, the AuthSubRequest URL might look like this:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.google.com%2Fm8%2Ffeeds%2F&session=1&secure=0&hd=domain.com&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

The user follows the link to Google's site and authenticates to their Google Account.

After the user authenticates, the AuthSub system redirects them to the URL you specified in the next query parameter of the AuthSubRequest URL. The AuthSub system appends an authentication token to that URL, as the value of the token query parameter. For example:

http://www.example.com/welcome.html?auth_sub_scopes=http://www.google.com/m8/feeds/&token=yourAuthToken

This token value represents a single-use AuthSub token. In this example, since session=1 was specified, this token can be exchanged for an AuthSub session token by calling the AuthSubSessionToken service with the single-use token in an Authorization header like this:

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourAuthToken"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

The AuthSubSessionToken service response includes a Token header that contains the session token and an Expiration header that indicates how long the token will remain valid.

Your application can then use the session token value in the Authorization header of subsequent interactions with contacts.

Here's an example of an HTTP request, containing a non-secure token, that you might send to request a contacts feed:

GET /m8/feeds/contacts/example.com/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourSessionToken"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

ClientLogin username/password authentication

Use ClientLogin authentication if your client is a standalone, single-user "installed" client (such as a desktop application). To request an authentication token using the ClientLogin mechanism, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The POST body should contain a set of query parameters that look like parameters passed by an HTML form, using the application/x-www-form-urlencoded content type. These parameters are:

Parameter Description
accountType Type of account to be authenticated. This should be set to HOSTED.
Email The user's email address.
Passwd The user's password, or your access code if enrolled in two-step verification.
service The service name for contacts feeds is cp. (For other service names, see the service name list.)
source Identifies your client application. Should take the form companyName-applicationName-versionID. The examples use the name exampleCo-exampleApp-1.

For more information about the parameters, see the Authentication for Installed Applications document.

If the authentication request fails, then the server returns an HTTP 403 Forbidden status code.

If it succeeds, then the server returns an HTTP 200 OK status code, plus three long alphanumeric codes in the body of the response: SID, LSID, and Auth. The Auth value is the authorization token that you'll send with each of your subsequent contacts-feed requests, so keep a copy of that value. You can ignore the SID and LSID values.

Since all requests to private feeds require authentication, you have to set the Authorization header in all subsequent interactions with contacts feeds, using the following format:

Authorization: GoogleLogin auth=yourAuthToken

Where yourAuthToken is the Auth string returned by the ClientLogin request.

For more information about ClientLogin authentication, including sample requests and responses, see the Account Authentication for Installed Applications documentation.

Note: Use the same token for all requests in a given session; don't acquire a new token for each contacts request.

Domain Shared Contacts feed URL

The feed URL takes the following form:

https://www.google.com/m8/feeds/contacts/domain/full

where domain is the name of the domain in question (e.g. example.com).

Note: "full" can be replaced with other projection values.

Note: Only the authenticated user's email address or the name of the domain the user is an administrator of can be specified in the URL.

Specifying a version

Every request that you send using the Shared Contacts Data API should specify version 3.0 of the API.

To specify a version number, use the GData-Version HTTP header:

GData-Version: 3.0

Alternatively, if you can't set HTTP headers, you can specify v=3.0 as a query parameter in the URL. But the HTTP header is preferred where possible.

Note: The client libraries supply appropriate version headers automatically, so don't use the v=3.0 query parameter when you're using a client library.

Creating shared contacts

After authenticating, you can publish new shared contact entries.

First, create an XML representation of the shared contact to publish. This XML needs to be in the form of an Atom <entry> element of the Contact kind, which might look like this:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <atom:category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/contact/2008#contact' />
  <gd:name>
     <gd:givenName>Elizabeth</gd:givenName>
     <gd:familyName>Bennet</gd:familyName>
     <gd:fullName>Elizabeth Bennet</gd:fullName>
  </gd:name>
  <atom:content type='text'>Notes</atom:content>
  <gd:email rel='http://schemas.google.com/g/2005#work'
    primary='true'
    address='liz@gmail.com' displayName='E. Bennet' />
  <gd:email rel='http://schemas.google.com/g/2005#home'
    address='liz@example.org' />
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#work'
    primary='true'>
    (206)555-1212
  </gd:phoneNumber>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#home'>
    (206)555-1213
  </gd:phoneNumber>
  <gd:im address='liz@gmail.com'
    protocol='http://schemas.google.com/g/2005#GOOGLE_TALK'
    primary='true'
    rel='http://schemas.google.com/g/2005#home' />
  <gd:structuredPostalAddress
      rel='http://schemas.google.com/g/2005#work'
      primary='true'>
    <gd:city>Mountain View</gd:city>
    <gd:street>1600 Amphitheatre Pkwy</gd:street>
    <gd:region>CA</gd:region>
    <gd:postcode>94043</gd:postcode>
    <gd:country>United States</gd:country>
    <gd:formattedAddress>
      1600 Amphitheatre Pkwy Mountain View
    </gd:formattedAddress>
  </gd:structuredPostalAddress>
</atom:entry>

To publish this entry, send it to the contact-list feed URL as follows. First, place your Atom <entry> element in the body of a new POST request, using the application/atom+xml content type. Then send it to the feed URL. For example, to add a domain shared contact to the list belonging to example.com, post the new entry to the following URL:

https://www.google.com/m8/feeds/contacts/example.com/full

The Google server creates a contact using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new contact in the form of an <entry> element. The entry returned is the same one you sent, but it also contains various elements added by the server, such as an <id> element.

Note: A contact's photo cannot be set while creating a contact. See: Photo management.

If your request fails for some reason, Google may return a different status code. For information about the status codes, see the Google Data API protocol reference document.

Note: Created shared contacts can take up to 24 hours to appear in the email address auto-complete and the contact manager.

Retrieving shared contacts

Retrieving all shared contacts

To retrieve the user's contacts, send an HTTP GET request to the contacts feed URL. Google then returns a feed containing the appropriate contact entries. For example, to get a list of domain shared contacts for example.com, send the following HTTP request:

GET https://www.google.com/m8/feeds/contacts/example.com/full

The feed then returns an HTTP 200 OK status code and a standard Atom 1.0 feed containing the contacts.

Note: The feed will not return more than 10MB in a single response. Attempts to do so will result in truncated data. For information on limiting the number of results returned, see the max-results query parameter in Retrieving contacts using query parameters. You can retrieve the entire contact list by repeatedly following the returned feed's next link, until no such link can be found.

The following is an example of a contacts feed with only one entry.

<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
    xmlns:gd='http://schemas.google.com/g/2005'
    xmlns:gContact='http://schemas.google.com/contact/2008'
    xmlns:batch='http://schemas.google.com/gdata/batch'>
  <id>https://www.google.com/m8/feeds/contacts/example.com/base</id>
  <updated>2008-03-05T12:36:38.836Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/contact/2008#contact' />
  <title type='text'>example.com's Contacts</title>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full' />
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full' />
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full/batch' />
  <link rel='self' type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full?max-results=25' />
  <author>
    <name>example.com</name>
    <email>example.com</email>
  </author>
  <generator version='1.0' uri='https://www.google.com/m8/feeds/contacts'>
    Contacts
  </generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry>
    <id>
      https://www.google.com/m8/feeds/contacts/example.com/base/c9012de
    </id>
    <updated>2008-03-05T12:36:38.835Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://schemas.google.com/contact/2008#contact' />
    <title type='text'>Fitzgerald</title>
    <gd:name>
      <gd:fullName>Fitzgerald</gd:fullName>
    </gd:name>
    <link rel="http://schemas.google.com/contacts/2008/rel#photo" type="image/*"
      href="http://google.com/m8/feeds/photos/media/example.com/c9012de"/>
    <link rel='self' type='application/atom+xml'
      href='https://www.google.com/m8/feeds/contacts/example.com/full/c9012de' />
    <link rel='edit' type='application/atom+xml'
      href='https://www.google.com/m8/feeds/contacts/example.com/full/c9012de/1204720598835000' />
    <gd:phoneNumber rel='http://schemas.google.com/g/2005#home'
      primary='true'>
      456
    </gd:phoneNumber>
    <gd:extendedProperty name="pet" value="hamster" />
  </entry>
</feed>

Retrieving shared contacts using query parameters

The Shared Contacts API lets you request a set of contacts that match specified criteria, such as requesting contacts updated after a given date.

For example, to send a date-range query, add the updated-min parameter to the request URL. To get all the domain shared contact entries updated after March 16, 2007, send an HTTP request to the domain shared contact feed URL:

GET https://www.google.com/m8/feeds/contacts/example.com/full?updated-min=2007-03-16T00:00:00

When you send that GET request, the server returns an HTTP 200 OK status code and a feed containing any domain shared contacts that were created or updated after the date specified.

The Domain Shared Contacts API supports query parameters described in the Shared Contacts API Reference Guide (see also: Google Data APIs Reference Guide). In particular, there is no support for full-text queries or locating a contact by email address.

Hint: To track incremental changes to a domain shared contact list, do the following: When you send a request for a feed, keep track of the value of the feed's <updated> element. Then you can later retrieve only the domain shared contacts that have changed since the previous request by setting the query parameter updated-min to that <updated> value, and setting showdeleted to true.

Note: By default, the entries in a feed are not ordered.

Retrieving a single shared contact

To retrieve a specific domain shared contact, send an HTTP GET request to the self link of this contact. The server returns a domain shared contact entry. For example, to get a domain shared contact with self link set to https://www.google.com/m8/feeds/contacts/example.com/full/12345, send the following HTTP request:

GET https://www.google.com/m8/feeds/contacts/example.com/full/12345

The server then returns an HTTP 200 OK status code and an entry containing the contact.

Note: Retrieving a single shared contact requires prior knowledge of the entry's self link, which can only be obtained by locating the corresponding entry in the shared contacts feed. See Retrieving all contacts and Retrieving contacts using query parameters for more information.

Retrieving a photo for a contact

To retrieve a photo for a contact, send an HTTP GET request to the photo link of this contact. The server returns bytes of the photo. For example, to get the latest version of a photo for a contact with an element:

<link rel="http://schemas.google.com/contacts/2008/rel#photo" type="image/*"
    href="https://google.com/m8/feeds/photos/media/example.com/c9012de"/>

send the following HTTP request:

GET https://google.com/m8/feeds/photos/media/example.com/c9012de

The server then returns an HTTP 200 OK status code and the photo.

Note: If a contact does not have a photo, then the photo link element has no gd:etag attribute.

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

Updating shared contacts

To update an existing shared contact, first retrieve the entry you want to update, modify it, and then send a PUT request with the updated entry in the message body to the contact's edit URL. Use the application/atom+xml content type. Be sure that the <id> value in the entry you PUT exactly matches the <id> of the existing entry.

Note: The shared contact's name is stored in the <atom:title> element.

The edit URL ends with a version number, in order to detect conflicts of updates from different sources; for more information, see the versioning section of the Google Data APIs reference guide.

The edit URL is highlighted in the following entry:

<entry>
  <id>https://www.google.com/m8/feeds/contacts/example.com/base/8411573</id>
  <updated>2008-02-28T18:47:02.303Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/contact/2008#contact' />
  <title type='text'>Fitzgerald</title>
  <gd:name>
    <gd:fullName>Fitzgerald</gd:fullName>
  </gd:name>
  <content type='text'>Notes</content>
  <link rel='self' type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full/8411573' />
  <link rel='edit' type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full/8411573/1204224422303000' />
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#other'
    primary='true'>456-123-2133</gd:phoneNumber>
  <gd:extendedProperty name="pet" value="hamster" />
  <gd:extendedProperty name="cuisine">
    <italian />
  </gd:extendedProperty>
</entry>

Important: To ensure forward compatibility, be sure that when you PUT an updated entry you preserve all the XML that was present when you retrieved the entry from the server. Otherwise the ignored elements will be deleted. The Google Data API client libraries all handle this correctly, so if you're using one of the libraries you're all set.

Troubleshooting Tip: Some firewalls block HTTP PUT messages. To get around this, you can include a X-HTTP-Method-Override: PUT header in a POST request. For details, see the Google Data API protocol basics document.

Important: Setting extended properties (gd:extendedElement elements) is allowed only within full or property-NAME projection.

Note: Updates can take up to 24 hours to be reflected in the email address auto-complete and the contact manager.

Shared contact photo management

Every shared contact has an photo link element. It has the form:

    <link rel="http://schemas.google.com/contacts/2008/rel#photo" type="image/*"
      href="https://www.google.com/m8/feeds/photos/media/liz%40example.com/c9012de">

That element appears whether the contact has an associated photo or not. If the contact does have a photo, then the element contains a gd:etag attribute specifying an ETag for the photo. If the contact has no photo, then there's no gd:etag attribute, and the href attribute provides the URL to use to add a photo to the contact.

To add or update a photo from the link above, send a new photo with a PUT command to the URL: https://www.google.com/m8/feeds/photos/media/liz%40example.com/c9012de. Remember to set a proper "image/*" Content-Type header.

To delete a photo, using DELETE HTTP method is required.

When updating or deleting a photo, send the photo's ETag in the If-Match header of the HTTP request. Alternatively, use If-Match: * to update or delete regardless of whether you have the latest version of the photo.

For more information about ETags, see the Google Data APIs reference guide.

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

Deleting shared contacts

To delete a shared contact, send a DELETE request to the contact's edit URL. This is the same URL used to update contacts. (Google retains placeholders for deleted contacts for 30 days after deletion; during that time, you can request the placeholders using the showdeleted query parameter.)

Troubleshooting Tip: Some firewalls block HTTP DELETE messages. To get around this, you can include a X-HTTP-Method-Override: DELETE header in a POST request. For details, see the Google Data API protocol basics document.

Note: To update existing contacts, see Updating contacts; don't update by deleting contacts and then re-adding them.

Note: Deleted shared contacts can take up to 24 hours to disappear from the email address auto-complete and the contact manager.

Batch operations

If you're performing a lot of operations, the time it takes to send and and receive all those HTTP messages can really add up, making your app slow and unresponsive. With batch requests you can have the server perform multiple operations with a single HTTP request. The basic idea is that you create a contacts feed and add an entry for each operation you want to perform.

The following snippet shows a batch request that contains two create operations, however you can use also querying, updating, and deleting contacts. Most of the unnecessary elements have been omitted.

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:gContact='http://schemas.google.com/contact/2008'
      xmlns:gd='http://schemas.google.com/g/2005'
      xmlns:batch='http://schemas.google.com/gdata/batch'>
  <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://schemas.google.com/g/2008#contact' />
  <entry>
    <batch:id>1</batch:id>
    <batch:operation type='insert' />
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://schemas.google.com/g/2008#contact'/>
    <gd:name>
      <gd:givenName>Contact</gd:fullName>
      <gd:familyName>One</gd:fullName>
    </gd:name>
    <gd:email rel='http://schemas.google.com/g/2005#home'
      address='contact1@example.com' primary='true'/>
  </entry>
  <entry>
    <batch:id>2</batch:id>
    <batch:operation type='insert' />
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://schemas.google.com/g/2008#contact'/>
    <gd:name>
      <gd:givenName>Contact</gd:fullName>
      <gd:familyName>Two</gd:fullName>
    </gd:name>
    <gd:email rel='http://schemas.google.com/g/2005#home'
      address='contact2@example.com'
      primary='true'/>
  </entry>
</feed>

Batch requests are limited to 100 operations at a time. You can find more information about batch operations in the Google Data Batch Processing documentation.

Note: The update and delete entries require an edit link in order for optimistic concurrency to work.

Note: Changes can take up to 24 hours to be reflected in the email address auto-complete and the contact manager.

Limits

The following summarizes the constraints that apply to the Shared Contacts Data API:

  • A single shared contact list may not contain more than 50,000 entries.
  • A single shared contact may not contain more than 2KB of data. (Note, however, that the total XML that represents the shared contact can be larger than 2KB.)
  • A response will be truncated if it exceeds 10MB in length.
  • One batch request may not include more than 100 operations.
  • Changes can take up to 24 hours to be reflected in the email address auto-complete and the contact manager.

Back to top

Appendices

Appendix A - Contacts feed types

The Shared Contacts Data API feeds is a private read/write feed that can be used by an adminstrator to view and manage domain's shared contacts. 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 a domain administrator. 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:

https://www.google.com/m8/feeds/contacts/Domain/projection

To request a particular representation of a contacts feed, a domain name and projection value have to be specified.

For example, the shared contacts feed for domain example.com and projection full would have the following URI:

https://www.google.com/m8/feeds/contacts/example.com/full

Appendix B - Extended Properties and projections

Extended Properties

It is possible to set additional shared contact related information as an extended property (arbitrary name - value pair) for a shared contact entry. Preserving key uniqueness is a responsibility of clients. The value of an 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 shared 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 properties are not displayed in the Google Contact Manager.

Example

Extended property with a key and a value:

<gd:extendedProperty name="com.google" value="some value"/>

Extended property with key and an XML blob:

<gd:extendedProperty name="com.google">
  <some_xml></some_xml>
</gd:extendedProperty>

To limit extended property visibility one can use projections.

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.

Appendix C - Contacts query parameters reference

The Shared 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 Shared 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 shared contacts are shown as entries that contain nothing but an <atom:id> element and a <gd:deleted> element. (Google retains placeholders for deleted shared 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.

Appendix D - Shared contacts elements reference

The Shared 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="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/contact/2008#contact"/>

In the Shared 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:structuredPostalAddress

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

gd:extendedProperty

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>
  <id>https://www.google.com/m8/feeds/contacts/example.com/base/8411573</id>
  <updated>2008-02-28T18:47:02.303Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/contact/2008#contact' />
  <title type='text'>Fitzgerald</title>
  <link rel="http://schemas.google.com/contacts/2008/rel#edit-photo" type="image/*"
    href="https://www.google.com/m8/feeds/photos/media/liz%40example.com/8411573/photo4524">
  <content type='text'>Notes</content>
  <link rel='self' type='application/atom+xml'
    href='https://www.google.com/m8/feeds/contacts/example.com/full/8411573' />
  <link rel='edit' type='application/atom+xml'
      href='https://www.google.com/m8/feeds/contacts/example.com/full/8411573/1204224422303000' />
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#other'
    primary='true'>456-123-2133</gd:phoneNumber>
  <gd:extendedProperty name="my-service-id" value="1234567890"/>
  <gd:extendedProperty name="my-second-service">
    <value-element>text value</value-element>
  </gd:extendedProperty>
</entry>

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

Photos support

Together with standard properties' values like self or edit, one can use rel values for atom:link element listed below:

  • rel="http://schemas.google.com/contacts/2008/rel#photo", adds the capability of reading (through a GET command) the photo associated with the contact. URL specified in href can be used to read the latest version of the photo associated with the contact. The link is not shown if there is no picture for the contact.

    Example link with the rel value:

    <atom:link rel="http://schemas.google.com/contacts/2008/rel#photo"
               href="https://www.google.com/m8/feeds/photos/media/jo%40example.com/1234" type="image/*" />
    
  • rel="http://schemas.google.com/contacts/2008/rel#edit-photo" adds the capability of updating or deleting (through PUT or DELETE command) of local photo associated with the contact.

    Example:

    <atom:link rel="http://schemas.google.com/contacts/2008/rel#edit-photo"
               href="https://www.google.com/m8/feeds/photos/media/jo%40example.com/1234/photo4524" />
    

Note: When using photo links, 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: http://schemas.google.com/contact/2008".

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

gContact:groupMembershipInfo

Properties

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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.