Click here to see your recently viewed pages and most viewed pages.

Google Documents List API v1 Developer's Guide: Protocol

Important: Versions 1 and 2 of the Google Documents List 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 the Google Drive API.

In addition to providing some background on the capabilities of the Documents List Data API, this guide provides examples for interacting with the API using the Java client library. For help setting up the client library, see Getting Started with the Google Data Java Client Library. If you're interested in understanding more about the underlying protocol used by the Java client library to interact with the Documents List Data API, please see the protocol tab.



This document is intended for developers who want to write client applications using the Google Data Java client library that can interact with Google Documents.

Getting started

Google Documents uses Google Accounts for authentication, so if you have a Google account you are all set. Otherwise, you can create a new account.

For help setting up the client library, see Getting Started with the Google Data Java Client Library. To use the Java client library, you must be running Java 1.5 or higher and include the jar files listed in the Dependencies wiki page. You'll find the classes you need to get started in the java/lib/gdata-document-1.0.jar and java/lib/gdataclient-1.0.jar jar files.

After downloading the client library, you'll find the sample explained in this guide in the sample/docs subdirectory of the distribution.

A full working copy of this sample is available in the Google Data Java Client Library project in the project hosting section of The sample is located at trunk/java/sample/docs/ in the SVN repository accessible from the Source tab.

The sample allows the user to perform a number of operations which demonstrate how to use the Documents List feed.

To compile the examples in this guide into your own code, you'll need to use the following import statements:

import sample.util.SimpleCommandLineParser;
import java.util.List;

The DocsService class represents a client connection (with authentication) to the Documents service. The general procedure for sending a query to a service using the client library consists of the following steps:

  1. Obtain or construct the appropriate URL.
  2. If you're sending data to a service (for example, if you're inserting a new entry), then transform the raw data into objects using the client library classes. (This step doesn't apply if you're just requesting a feed.)
  3. Create a new DocsService instance, setting your application's name (in the form companyName-applicationName-versionID).
  4. Set the appropriate credentials.
  5. Call a method to send the request and receive any results.

Authenticating to the Documents service

The Java client library can be used to work with either public or private feeds. The Documents List feed is private and requires authentication, so you will need to authenticate before performing operations. This can be done via ClientLogin username/password authentication or AuthSub proxy authentication. At this time, Google Documents only offers a private feed for Documents List.

Please see the authentication documentation for more information on AuthSub and ClientLogin.

ClientLogin for "installed" applications

To use ClientLogin (also called "Authentication for Installed Applications"), invoke the setUserCredentials method of DocsService inherited from GoogleService, specifying the ID and password of the user on whose behalf your client is sending the query. For example:

DocsService service = new DocsService("Document List Demo");
service.setUserCredentials("", password);

For more information about authentication systems, see the Google Account Authentication documentation.

AuthSub for web applications

AuthSub proxy authentication is used by web applications which need to authenticate their users to Google accounts. The website operator does not need access to the username and password for the Google Documents user - only special AuthSub tokens are required.

To acquire an AuthSub token for a given Google Documents user, your application must redirect the user to the AuthSubRequest URL, which prompts them to log into their Google account. You may use the getRequestUrl method on the AuthSubUtil object to create this URL:

String requestUrl = AuthSubUtil.getRequestUrl("", "", false, true);

The getRequestUrl method takes several parameters (corresponding to the query parameters used by the AuthSubRequest handler):

  • the next URL — URL that Google will redirect to after the user logs into their account and grants access; in the example above
  • the scope in the example above
  • a boolean to indicate whether the token will be used in registered mode or not; false in the example above
  • a second boolean to indicate whether the token will later be exchanged for a session token or not; true in the example above

After constructing the "next" URL, your server-side application can use it in a variety of ways to send the user to the AuthSubRequest handler. The most common approach is to display a page that tells the user that they need to follow a link to authorize your application to access your Google account; then attach the request URL to the link. For example, you could display the following string on a page:

String suggestAuthorization = "<p>MyApp needs access to your Google Docs account." + 
    "To authorize MyApp to access your account, <a href=\"" + requestUrl + "\">log in to your account</a>.</p>";

The user follows the link to the AuthSub page at Google, and logs in. The AuthSub system then redirects the user back to your application, using the "next" URL you provided.

When Google redirects back to your application, the token is appended to the "next" URL as a query parameter. So in the case of the above "next" URL, after the user logs in, Google redirects to a URL like

The user's browser is redirected to that URL. The servlet handling that URL should then examine the query parameters in the requested URL to retrieve the token set by Google. For example, the servlet can retrieve the token from the URL by using the convenience function getTokenFromReply from the Java client library:

String onetimeUseToken = AuthSubUtil.getTokenFromReply(httpServletRequest.getQueryString());

Your application can recognize which user has authenticated with Google's servers using AuthSub by setting an authentication cookie prior to having them click the AuthSub link, then reading this cookie after the user has been authenticated and returned to your webpage.

The token you retrieve with getTokenFromReply is always a one-time use token. You can exchange this token for a session token using the AuthSubSessionToken URL, as described in the AuthSub Authentication for Web Applications documentation. Your application can make this exchange using the Java client library as follows:

String sessionToken = AuthSubUtil.exchangeForSessionToken(onetimeUseToken, null);

You pass your one-time use token to the exchangeForSessionToken method, along with either null (for unregistered mode) or a private key (for registered mode), and the AuthSub interface returns a session token. For more information about registered applications and private keys, refer to the Using AuthSub with the Google Data API Client Libraries documentation.

You can use the session token to authenticate requests to the server by placing the token in the Authorization header, as described in the AuthSub Authentication for Web Applications documentation. To tell the Java client library to automatically send the Authorization header (containing the session token) with each request, you call the DocsService object's setAuthSubToken method:

DocsService myService = new DocsService("exampleCo-exampleApp-1");
service.setAuthSubToken(sessionToken, null);

If you're using registered mode, then you provide your private key instead of null.

After you've called setAuthSubToken, you can use the standard Data API client library calls to interact with the service, without having to think about the token.

If you want to retrieve information about the token's parameters, you can pass the token to the getTokenInfo method, which returns a set of name-value pairs containing information about the token. For example:

Map<String, String> info = AuthSubUtil.getTokenInfo(sessionToken, null);  

AuthSub session tokens don't expire; your client can store the session token for as long as needed.

When your client is done using the session token, it can revoke the token using the AuthSubRevokeToken handler, as described in the AuthSub Authentication for Web Applications documentation. For example, if you want to manage tokens in a traditional session-like way, then your client can get a token at the beginning of a user's session and revoke it at the end of the user's session.

To revoke a token using the Java client library, call revokeToken. Include your private key for registered mode, or null otherwise. For example:

AuthSubUtil.revokeToken(sessionToken, null);

See Using AuthSub with the Google Data API Client Libraries for more detailed information on using AuthSub in the Java client library.

Retrieving a list of documents

You can get a feed containing a list of the currently authenticated user's documents by sending an authenticated GET request to the following URL:

The result is a "meta-feed," a feed that lists all of that user's documents; each entry in the feed represents a document (spreadsheet or word processor document) associated with the user. This feed is only accessible using an authentication token.

You can print out a list of the user's documents with the following two functions:

public void showAllDocs() throws IOException, ServiceException {
  DocumentListFeed feed = service.getFeed(documentListFeedUrl,

  for (DocumentListEntry entry : feed.getEntries()) {

public void printDocumentEntry(DocumentListEntry doc) {
  String shortId = doc.getId().substring(doc.getId().lastIndexOf('/') + 1);
  System.out.println(" -- Document(" + shortId + "/" + doc.getTitle().getPlainText()
      + ")");

The resulting DocumentListFeed object feed represents a response from the server. Among other things, this feed contains a list of DocumentListEntry objects (feed.getEntries()), each of which represents a single document. DocumentListEntry encapsulates the information shown in the protocol document.

Uploading documents

To upload a document to the server you can attach the file to the new DocumentEntry using the setFile method. Once the file is associated with this entry, it's contents will be sent to the server when you insert the DocumentEntry. The example below shows how to upload a file when given the absolute path of a file.

public void uploadFile(String filePath) throws IOException,
    ServiceException {
  DocumentEntry newDocument = new DocumentEntry();
  File documentFile = new File(filePath);
  // Set the title for the new document. For this example we just use the
  // filename of the uploaded file.
  newDocument.setTitle(new PlainTextConstruct(documentFile.getName()));
  DocumentListEntry uploaded = service.insert(documentListFeedUrl, 

Note: that the above sample sets the name of the document to the file name, but you are free to choose a different name by passing in a string to the PlainTextConstruct constructor.

Uploading a word processor document

To upload a word processing document, you can use the example code above and specify a word processing file for the filePath.

Note: The client code uses the file's extension to determine its type.

Uploading a spreadsheet

Uploading a spreadsheet is done the same way as uploading a word processing document. If the file's extension indicates that it is a spreadsheet file, then it will be created as a spreadsheet.

Trashing a document

To delete a document, call the delete() method on the retrieved DocumentListEntry:


Searching the documents feed

You can search the Document List using some of the standard Google Data API query parameters. Categories are used to restrict the type of document (word processor document, spreadsheet) returned. The full-text query string is used to search the content of all the documents. More detailed information on parameters specific to the Documents List can be found in the Documents List Data API Reference Guide.

In the Java client library, a DocumentQuery object can be used to construct queries for the Documents List feed. The following code is used in all of the examples below to print out the feed results to the command line.

for (DocumentListEntry entry : feed.getEntries()) {

Here is the definition for the method printDocumentEntry:

public void printDocumentEntry(DocumentListEntry doc) {
  String shortId = doc.getId().substring(doc.getId().lastIndexOf('/') + 1);
  System.out.println(" -- Document(" + shortId + "/" + doc.getTitle().getPlainText()
      + ")");

Retrieving all word processor documents

A list of only word processor documents can be retrieved by appending the document category to the Documents List Feed URL as shown below:

DocumentListFeed feed = service.getFeed(new URL(documentListFeedUrl.toString() + "/-/document"), DocumentListFeed.class);

Retrieving all spreadsheets

A list of only spreadsheets can be retrieved by using the spreadsheet category as follows:

DocumentListFeed feed = service.getFeed(new URL(documentListFeedUrl.toString() + "/-/spreadsheet"), DocumentListFeed.class);

Performing a text query

You can search the content of documents by using a DocumentQuery in your query request. A DocumentQuery object can be used to construct the query URI, with the search term being passed in as a parameter. Here is an example method which queries the documents list for documents which contain the search string:

public void search(String fullTextSearchString) throws IOException,
    ServiceException {
  DocumentQuery query = new DocumentQuery(documentListFeedUrl);
  DocumentListFeed feed = service.query(query, DocumentListFeed.class);

  System.out.println("Results for [" + fullTextSearchString + "]");

  for (DocumentListEntry entry : feed.getEntries()) {

A more detailed description of how to use URL parameters to build complex queries can be found on the Google Data APIs Reference Guide.

Back to top