The Profiles Data API allows client applications to retrieve and update profile information for users in a Google Apps domain. Each user profile is stored in the owning user's Google Account, but it can be modified only by an administrator of the user's domain.
Your client application can use the Profiles Data API to retrieve the profiles of users in a Google Apps domain and to modify them on behalf of an administrator.
Profiles cannot be inserted or deleted, since every user is considered to have a profile, even if it is blank. Your client can populate a profile using an update operation. It can send an update operation with no content to clear existing profiles.
In addition to describing the capabilities of the Profiles Data API, this document provides examples of how to manipulate profiles 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.
This document is intended for programmers who want to write client applications that can interact with Google Apps users' profiles 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.
To test a program that uses the Google Apps Profiles API, you will need the username and password of a Google Apps administrator account. For testing purposes, you may want to register a test domain.
A Google Apps Profiles API feed is private to a Google Apps organization, and can only be used by an administrator in that organization. Thus, your client needs to authenticate before accessing a profile feed. Desktop clients should use ClientLogin username/password 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 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 user profiles.
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 profiles
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=example.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 profiles feed requests.
Here's an example of an HTTP request, containing a non-secure token, that you might send to request a profiles feed:
GET /m8/feeds/profiles/domain/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
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. |
service |
The service name for profiles 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 profiles-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 profiles 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 request.
The feed URL takes the following form:
http://www.google.com/m8/feeds/profiles/domain/domain/full
where domain is the name of the domain in question (such as example.com).
Note for those familiar with other Data APIs that use projections: full is currently the only projection supported by this feed.
Every request that you send using the Profiles 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. However, the HTTP header is preferred where possible.
Note: The client libraries supply appropriate version headers automatically, so don't use the v query parameter when you're using a client library.
To retrieve profiles for all users in a domain, send an HTTP GET request to the profiles feed URL. Google then returns a feed containing the appropriate profiles. For example, to get a list of profiles for users at example.com, send the following HTTP request:
GET http://www.google.com/m8/feeds/profiles/domain/example.com/full
The feed then returns an HTTP 200 OK status code and a standard Atom feed containing the profiles.
Note: The feed may not contain all of the domain's profiles, because there's a default limit on the number of results returned. For more information, see the max-results query parameter in Retrieving profiles using query parameters.
The following is an example of a profiles feed with only one entry.
|
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
xmlns:gContact='http://schemas.google.com/contact/2008'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gContact='http://schemas.google.com/contact/2008'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
<category scheme='http://schemas.google.com/g/2005#kind'
term='http://schemas.google.com/contact/2008#profile' />
<title>Elizabeth Bennet</title>
<gd:name>
<gd:givenName>Elizabeth</gd:givenName>
<gd:familyName>Bennet</gd:familyName>
</gd:name>
<gd:structuredPostalAddress rel='http://schemas.google.com/g/2005#work'>
<gd:formattedAddress>Longbourne, Nr. Meryton, Hertfordshire, England</gd:formattedAddress>
</gd:structuredPostalAddress>
</entry>
</feed>
The Profiles Data API lets you request a set of profiles that match specified criteria.
For example, to limit the number of results to receive, add the max-results parameter to the request URL. To get a feed containing no more than ten profile entries, send an HTTP request to the Profiles Data API's feed URL:
GET http://www.google.com/m8/feeds/profiles/domain/yourDomain/full?max-results=10
When you send that GET request, the Profiles Data API returns an HTTP 200 OK status code and a feed containing no more than the number of results you specified.
The Profiles Data API supports the following query parameters:
start-key value, but it is present in the next link of a previous Profiles Data API feed response. This allows pagination but not random access (in contrast to the start-index parameter used in typical GData queries).In particular, there is no support for full-text queries or ordering.
For more information about query parameters, see the Profiles Data API Reference Guide and the Google Data APIs Reference Guide.
Each profile entry in a profiles feed has a self link. To retrieve a specific profile, send an HTTP GET request to the profile's self link. The server returns a profile entry. For example, to get a profile for liz@example.com, send the following HTTP request:
GET http://www.google.com/m8/feeds/profiles/domain/example.com/full/liz
The server then returns an HTTP 200 OK status code and an entry containing the profile.
To update a profile, 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 profile's edit URL. Use the application/atom+xml content type. The edit URL is highlighted in the following entry:
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gContact='http://schemas.google.com/contact/2008'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
<category scheme='http://schemas.google.com/g/2005#kind'
term='http://schemas.google.com/contact/2008#profile' />
<id>http://www.google.com/m8/feeds/profiles/domain/example.com/full/liz</id>
<title>Elizabeth Bennet</title>
<link rel='self' type='application/atom+xml'
href='http://www.google.com/m8/feeds/profiles/domain/example.com/full/liz' />
<link rel='edit' type='application/atom+xml'
href='http://www.google.com/m8/feeds/profiles/domain/example.com/full/liz' />
<gd:name>
<gd:givenName>Elizabeth</gd:givenName>
<gd:familyName>Bennet</gd:familyName>
</gd:name>
<gd:structuredPostalAddress rel='http://schemas.google.com/g/2005#work'>
<gd:formattedAddress>Longbourne, Nr. Meryton, Hertfordshire, England</gd:formattedAddress>
</gd:structuredPostalAddress>
</entry>
Be sure that the <id> value in the entry you PUT exactly matches the <id> of the existing entry.
Note: The name and username fields cannot be changed through the Profiles Data API, because they are determined from the user's account information. If these fields are present in an update request, then they must match the existing values.
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 an X-HTTP-Method-Override: PUT header in a POST request. For details, see the Google Data API protocol basics document.
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 profiles feed and add an entry for each operation you want to perform.
The following snippet shows a batch request that retrieves two profiles in a single request. Most of the optional elements have been omitted.
<?xml version='1.0' encoding='UTF-8'?>
<feed
xmlns="http://www.w3.org/2005/Atom"
xmlns:batch='http://schemas.google.com/gdata/batch'>
<entry>
<batch:operation type="query"/>
<id>http://www.google.com/m8/feeds/profiles/domain/example.com/full/liz</id>
</entry>
<entry>
<batch:operation type="query"/>
<id>http://www.google.com/m8/feeds/profiles/domain/example.com/full/darcy</id>
</entry>
</feed>
Batch requests are limited to 100 operations at a time. You can find more information about batch operations in the Google Data APIs Batch Processing documentation.
For information about the standard Google Data API elements, see the Atom specification and the Kinds document.