Developer's Guide: The Protocol

The Google Documents List Data API allows client applications to view and update documents (spreadsheets and word processor) using a Google Data API feed. Your client application can request a list of a user's documents, query the content of a user's documents, and upload new documents.

Contents

Audience

This document is intended for programmers who want to write client applications that can interact with Google Documents. It provides a series of examples of basic data API interactions using raw XML/HTTP, with explanations. After reading this document, you can learn more about interacting with the API using our client libraries by reading the language-specific examples found on the other tabs at the top of this document.

For Documents List Data API reference information, see the reference guide.

This document assumes that you understand the general ideas behind the Google data APIs protocol. Each example in this document first shows how to use the bare protocol to interact with Documents.

Authenticating to the Documents service

To request or upload documents, your client needs an authentication token. The following sections explain how to authenticate for different types of client applications.

Your choice of authentication method should be determined by the kind of client you're writing: single-user desktop applications should use the ClientLogin system, while multi-user web apps should use the AuthSub system. For a more detailed discussion of these authentication systems, see the Google Account Authentication document.

Whichever method you choose, you can either send raw HTTP requests or have Google's client libraries handle the authentication for you.

Single-user "installed" client authentication

To authenticate the user, send a POST request to the following URL:

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

Include the relevant parameters in the body of the POST request, as described in the ClientLogin documentation. The service name for Documents is writely.

If the request succeeds, then the response contains an alphanumeric string labeled Auth.

After a successful authentication request, use the Auth value to create an Authorization header for each request:

Authorization: GoogleLogin auth=yourAuthValue

Multiple-user web application client authentication

To acquire an AuthSub token for a given Documents user, your application must redirect the user to the AuthSubRequest URL at Google, which prompts them to log into their Google account.

After the user logs in, 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 the next URL as the value of the token query parameter. Your application then uses that authentication token in subsequent interactions with Documents.

The below example shows a request to authorize www.example.com:

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

Upgrading to a session token

By default, the AuthSub token can only be used for one request. To receive a token which can be used for multiple requests, it must be upgraded by making an HTTP GET request which contains the single use token as an Authorization header. A token may only be upgraded if the initial AuthSub request included session=1 as a URL parameter.

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: https://www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

If the token was upgraded successfully, the server's response contains the new token information in the HTTP headers. Here's an example response:

Token=DQAA...7DCTN
Expiration=20061004T123456Z

Use the authentication token to create an Authorization header for each request:

Authorization: AuthSub token="yourAuthToken"

For details, including information on registering your application with Google and other topics, see the AuthSub documentation.

Note: The token value in the Authorization header should be surrounded by quotation marks.

Retrieving a list of documents

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

http://docs.google.com/feeds/documents/private/full

The result is 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 accessible only using an authentication token.

Entries in the Documents List feed might look something like the following:

<entry>
  <content src="http://spreadsheets.google.com/fm?fmcmd=102&key=key"
  type="text/html" />
  <author>
    <name>test.user</name>
    <email>test.user@gmail.com</email>
  </author>
  <category label="spreadsheet"
  scheme="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/docs/2007#spreadsheet" />
  <category label="My Favorite Spreadsheets"
  scheme="http://schemas.google.com/docs/2007/folders/user_email"
  term="My Favorite Spreadsheets" />
  <id>http://docs.google.com/feeds/documents/private/full/spreadsheet%3Akey</id>
  <link href="http://spreadsheets.google.com/ccc?key=key"
  rel="alternate" type="text/html" />
  <link href="http://spreadsheets.google.com/feeds/worksheets/key/private/full"
  rel="http://schemas.google.com/spreadsheets/2006#worksheetsfeed"
  type="application/atom+xml" />
  <link href="http://docs.google.com/feeds/documents/private/full/spreadsheet%3Akey"
  rel="self" type="application/atom+xml" />
  <title type="text">Test Spreadsheet</title>
  <updated>2007-07-03T18:03:32.045Z</updated>
</entry>
<entry>
  <content src="http://docs.google.com/RawDocContents?action=fetch&docID=document_id"
  type="text/html" />
  <author>
    <name>test.user</name>
    <email>test.user@gmail.com</email>
  </author>
  <category label="document"
  scheme="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/docs/2007#document" />
  <category label="starred"
  scheme="http://schemas.google.com/g/2005/labels"
  term="http://schemas.google.com/g/2005/labels#starred" />
  <id>http://docs.google.com/feeds/documents/private/full/document%3Adocument_id</id>  
  <link href="http://foobar.com/Doc?id=document_id" rel="alternate"
  type="text/html" />
  <link href="http://docs.google.com/feeds/documents/private/full/document%3Adocument_id"
  rel="self" type="application/atom+xml" />
  <title type="text">Test Document</title>
  <updated>2007-07-03T18:02:50.338Z</updated>
</entry>

The first entry is a spreadsheet that is contained in a folder named "My Favorite Spreadsheets" and the second entry is a starred word processor document. Notice that their types can be distinguished by the category element with the http://schemas.google.com/g/2005#kind scheme. The spreadsheet key in the example has been replaced with key and the word processor document id has been replaced with document_id. For the spreadsheet example's folder, the user's email address has been replaced with user_email.

Uploading documents

Documents are uploaded to the server via an HTTP POST optionally using MIME multipart encoding to combine the the document contents with a Atom entry describing the document. Any combination of Atom entry and an HTTP Slug header can be used to specify the title of the uploaded document, but the following precedence will determine the final document name:

1. The Atom entry <atom:title/> if present
2. The HTTP Slug header value if present
3. A default filename chosen by Google Documents

Currently you can upload word processor documents, spreadsheets and presentations. A list of accepted formats can be found here.

Uploading a word processor document with metadata

Here is an example of uploading a document named test.doc on the client computer which will be called example document on Google Documents (See Uploading Docs for the precedence rules that determine this document name).

POST /feeds/documents/private/full HTTP/1.1
Content-Length: 73612
Content-Type: multipart/related; boundary=END_OF_PART
Slug: test.doc
MIME-version: 1.0

Media multipart posting
--END_OF_PART
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:category scheme="http://schemas.google.com/g/2005#kind" 
      term="http://schemas.google.com/docs/2007#document" />
  <atom:title>example document</atom:title>
</atom:entry>
--END_OF_PART
Content-Type: application/msword

... doc contents here ...

--END_OF_PART--

If the upload is successful, a 201 Created response will be returned along with a Atom entry describing the document on the server.

Uploading a spreadsheet without metadata

Here is an example of uploading a spreadsheet which will be called Example Spreadsheet on Google Documents.

POST /feeds/documents/private/full HTTP/1.1
Content-Length: 81047
Content-Type: application/vnd.ms-excel
Slug: Example Spreadsheet

... spreadsheet contents here ...

Again, if the upload is successful, a 201 Created response will be returned along with a Atom entry describing the document on the server.

Trashing documents

To put a document in the trash, send an HTTP DELETE request to the edit link. The edit link will have a document id and a version token represented by id and version respectively in the example below:

DELETE /feeds/documents/private/full/spreadsheet%3Aid/version

AIf you try to trash using a version number other than the latest one, you may receive an error; for more information, see Optimistic concurrency (versioning) in the Google Data reference document.

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. Please note that the DocList API currently does not support excluding folders using the /category/-starred syntax.

Retrieving all word processor documents

A list of only word processor documents can be retrieved by using the document category as follows:

  GET /feeds/documents/private/full/-/document

For an examply entry of the feed that will be returned, look at the Retrieving a list of documents section.

Retrieving all starred presentations

A list of only starred presentations can be retrieved by using the presentation and starred categories as follows:

  GET /feeds/documents/private/full/-/presentation/starred

For an examply entry of the feed that will be returned, look at the Retrieving a list of documents section.

Retrieving all documents in a folder named "starred"

A list of only documents contained in a folder named "starred" created by the current user with email address email can be retrieved by using a scheme qualified folder category to disambiguate from a starred category query for starred documents as follows:

  GET /feeds/documents/private/full/-/{http:%2F%2Fschemas.google.com%2Fdocs%2F2007%2Ffolders%2Femail}starred

For an examply entry of the feed that will be returned, look at the Retrieving a list of documents section.

Performing a text query

You can search the content of documents by using the q query parameter on the feed. For example, if you wanted to search a user's documents for the string "example query" you could do the following authenticated GET:

  GET /feeds/documents/private/full?q=example+query

A more detailed description of how the q parameter works can be found on the Google Data APIs Reference Guide.

Back to top