Google Documents List Data API v3.0 (Labs)

Documents List Data API
- Developer's Guide
- - Version 3.0 ^(Labs ⁾
  - Version 2.0
  - Version 1.0
    - Protocol Guide
    - Reference Guide
    - Java
    - .NET
    - PHP
    - Python
- API Changelog
- Libraries and Code
- Solutions Marketplace

Google Data Protocol

Protocol Guide (v3.0)

Important: The Google Documents List Data API v3.0 is in Labs, and its features might change unexpectedly until it graduates. Version 2.0 is the latest graduated version.

Audience
Authenticating to the Documents service
Specifying a version
Retrieving a list of documents
1. Retrieving a list or resource again
Searching the documents feed
Retrieving folder contents
Uploading documents
Updating documents
Deleting documents and folders
1. Trashing a document or folder
2. Deleting a document or folder ^New

Downloading documents
Creating folders
1. Creating a subfolder
Moving documents and folders
Modifying Document and Folder Sharing Permissions
Document Revisions ^New
1. Retrieving document revisions
2. Downloading a revision
Special Features ^New
1. Optical Character Recognition (OCR)
2. Document Translation

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, while multi-user web applicatoins should use the AuthSub or OAuth. 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.

AuthSub for web applications

AuthSub Authentication for Web Applications should be used by client applications which need to authenticate their users to Google accounts. The operator does not need access to the username and password for the Google Documents user - only an AuthSub token is required.

View instructions for incorporating AuthSub into your web application Show rest of description Hide rest of description

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 the Documents List API.

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%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

The scope parameter for the Documents List API is http://docs.google.com/feeds/. You can also use SSL: https://docs.google.com/feeds/. For a list of valid scopes for other Google Data APIs, see the FAQ.

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="yourSingleUseToken"
Host: https://www.google.com
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

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

Authorization: AuthSub token="yourSessionToken"

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

OAuth for web applications

OAuth can be used as an alternative to AuthSub, and is intended for web applications. OAuth is similar to using the secure and registered mode of AuthSub in that all data requests must be digitally signed and you must register your domain.

View instructions for incorporating OAuth into your web application Show rest of description Hide rest of description

This document does not discuss the details on how to obtain an OAuth access token. Please see the full OAuth Authentication for Web Applications documentation on how to do that. Once you have an OAuth access token, your client may send requests by constructing an appropriate oauth_signature and Authorization header.

Example request

To send an HTTP GET to http://docs.google.com/feeds/default/private/full?title=MyTitle, first construct the signature base string:

GET&http%3A%2F%2Fdocs.google.com%2Ffeeds%2Fdefault%2Fprivate%2Ffull%2F&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D38863f48...28dd9fd2c%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1249972977%26oauth_token%3D1%252Fz1...LMzNBrKhElA%26oauth_version%3D1.0%26title%3DMyTitle

Set the oauth_signature to the result of signing the base string with the algorithm you specify in oauth_signature_method. The example request would look like this:

GET /feeds/default/private/full/?title=MyTitle HTTP/1.1
Host: docs.google.com
Accept: */*
Authorization: OAuth oauth_version="1.0", oauth_nonce="38863f48...28dd9fd2c", oauth_timestamp="1249972977", oauth_consumer_key="example.com", oauth_token="1%2Fz1...LMzNBrKhElA", oauth_signature_method="RSA-SHA1", oauth_signature="kH%2BjQd%2Ba8...odMeUnsU%2FxANOw%3D"

This example assumes example.com has already been registered with Google.

For more information on constructing the OAuth base string and Authorization header, see the reference links at the end of this authentication section.

ClientLogin for installed/mobile applications

ClientLogin should be used by installed or mobile applications which need to authenticate their users to Google accounts. On first run, your application prompts the user for their username/password. On subsequent requests, an authentication token is referenced.

View instructions for incorporating ClientLogin into your installed/mobile application Show rest of description Hide rest of description

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

Need more information on authorization?

More details on working with the different authentication methods, including information on registering your web application with Google and other topics, see:

General AuthSub Overview, and AuthSub Authentication for Web Applications (full documentation)
General ClientLogin Overview, and Authentication for Installed Applications (full documentation)
General OAuth Overview, and OAuth Authentication for Web Applications (full documentation)
Using AuthSub with the Google Data API Client Libraries
Using OAuth with the Google Data API Client Libraries
Using ClientLogin with the Google Data API Client Libraries

Specifying a version

Every request that you send using the Documents List Data API should specify version 3 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 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 query parameter when you're using a 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:

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

The result is a feed that lists all of that user's documents; each entry in the feed represents a 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:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns:docs="http://schemas.google.com/docs/2007" xmlns:batch="http://schemas.google.com/gdata/batch"
    xmlns:gd="http://schemas.google.com/g/2005" gd:etag="W/"DUMFR3YyfCt7ImA9WxNTFU0."">
<id>http://docs.google.com/feeds/default/private/full</id>
<updated>2009-08-17T11:10:16.894Z</updated>
<title>Available Documents - user@gmail.com</title>
<link rel="alternate" type="text/html" href="http://docs.google.com"/>
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full"/>
<link rel="http://schemas.google.com/g/2005#batch" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full/batch"/>
<link rel="self" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full/"/>
<author>
  <name>user</name>
  <email>user@gmail.com</email>
</author>
<openSearch:startIndex>1</openSearch:startIndex>
<entry gd:etag="'EVJVTBICRit7ImBq'">
  <id>http://docs.google.com/feeds/id/document%3A12345</id>
  <published>2009-07-22T19:02:57.616Z</published>
  <updated>2009-07-29T20:31:39.804Z</updated>
  <app:edited xmlns:app="http://www.w3.org/2007/app">2009-07-31T17:21:26.497Z</app:edited>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/docs/2007#document" label="document"/>
  <category scheme="http://schemas.google.com/g/2005/labels" term="http://schemas.google.com/g/2005/labels#viewed" label="viewed"/>
  <title>Document's Title</title>
  <content type="text/html" src="http://docs.google.com/feeds/download/documents/Export?docId=12345"/>
  <link rel="http://schemas.google.com/docs/2007#parent" type="application/atom+xml"
        href="http://docs.google.com/feeds/default/private/full/folder%3A12345" title="AFolderName"/>
  <link rel="alternate" type="text/html" href="http://docs.google.com/Doc?docid=12345&amp;hl=en"/>
  <link rel="self" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full/document%3A12345"/>
  <link rel="edit" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full/document%3A12345"/>
  <link rel="edit-media" type="text/html" href="http://docs.google.com/feeds/default/media/document%3A12345"/>
  <author>
    <name>user</name>
    <email>user@gmail.com</email>
  </author>
  <gd:resourceId>document:12345</gd:resourceId>
  <gd:lastModifiedBy>
    <name>user</name>
    <email>user@gmail.com</email>
  </gd:lastModifiedBy>
  <gd:lastViewed>2009-07-31T17:21:26.273Z</gd:lastViewed>
  <gd:quotaBytesUsed>0</gd:quotaBytesUsed>
  <docs:writersCanInvite value="true"/>
  <gd:feedLink rel="http://schemas.google.com/acl/2007#accessControlList"
       href="http://docs.google.com/feeds/default/private/full/document%3A12345/acl"/>
  <gd:feedLink rel="http://schemas.google.com/docs/2007/revisions"
       href="http://docs.google.com/feeds/default/private/full/document%3A12345/revisions"/>
</entry>
<entry xmlns:gd="http://schemas.google.com/g/2005" gd:etag="'HhJSFgpeRyt7ImBq'">
  <id>http://docs.google.com/feeds/id/pdf%3A12345</id>
  <published>2009-04-09T18:23:09.035Z</published>
  <updated>2009-04-09T18:23:09.035Z</updated>
  <app:edited xmlns:app="http://www.w3.org/2007/app">2009-06-18T22:16:02.388Z</app:edited>
  <category scheme="http://schemas.google.com/g/2005/labels" term="http://schemas.google.com/g/2005/labels#starred" label="starred"/>
  <category scheme="http://schemas.google.com/g/2005/labels" term="http://schemas.google.com/g/2005/labels#viewed" label="viewed"/>
  <category scheme="http://schemas.google.com/g/2005/labels" term="http://schemas.google.com/g/2005/labels#hidden" label="hidden"/>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/docs/2007#pdf" label="pdf"/>
  <title>PDF's Title</title>
  <content type="application/pdf"
       src="http://doc-04-20-docs.googleusercontent.com/docs/secure/m71240...U1?h=1630126&amp;e=download&amp;gd=true"/>
  <link rel="alternate" type="text/html" href="http://docs.google.com/fileview?id=12345&amp;hl=en"/>
  <link rel="self" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full/pdf%3A12345"/>
  <link rel="edit" type="application/atom+xml" href="http://docs.google.com/feeds/default/private/full/pdf%3A12345"/>
  <link rel="edit-media" type="application/pdf" href="http://docs.google.com/feeds/default/media/pdf%3A12345"/>
  <author>
    <name>user</name>
    <email>user@gmail.com</email>
  </author>
  <gd:resourceId>pdf:12345</gd:resourceId>
  <gd:lastModifiedBy>
    <name>user</name>
    <email>user@gmail.com</email>
  </gd:lastModifiedBy>
  <gd:lastViewed>2009-06-18T22:16:02.384Z</gd:lastViewed>
  <gd:quotaBytesUsed>108538</gd:quotaBytesUsed>
  <docs:writersCanInvite value="false"/>
  <gd:feedLink rel="http://schemas.google.com/acl/2007#accessControlList"
       href="http://docs.google.com/feeds/default/private/full/pdf%3A12345/acl"/>
</entry>
...
</feed>

The first entry is a document that is contained in a folder named "AFolderName" (designated by the Atom <link> with rel value http://schemas.google.com/docs/2007#parent. The second entry is a starred, hidden, PDF that has been viewed by the requesting user. Notice that the type of entry can be distinguished by the category element with the http://schemas.google.com/g/2005#kind scheme.

Document resource ID

This document often refers to the notion of a "document ID" and a document "resource ID". A document's resource ID can be found in the Atom entry under <gd:resourceId>. Its value can be used in a number of places, most notably when exporting the document or querying for the document again. Each resource ID includes the type of document and the document's unique ID:

<gd:resourceId>type:docID</gd:resourceId>

For example, in the first XML entry above, the resource ID is document:12345 and the the docID is 12345. It is recommend that you store a document's full resource ID rather than just the document ID because the type is contained within the entire resource ID.

Retrieving a list or resource again

If you want to retrieve a document list or entry that you've retrieved before, you can improve efficiency by telling the server to send the list or entry only if it has changed since the last time you retrieved it.

To do this sort of conditional retrieval, send an HTTP GET request that includes an HTTP If-None-Match header. In the header, specify the list's or entry's ETag, which you can find in the <feed> element's or <entry> element's gd:etag attribute.

For example:

GET /feeds/default/private/full/resource_id
GData-Version: 3.0
If-None-Match: "BxAaTxRZAyp7ImBq"

When the server receives this request, it checks to see whether the item that you requested has the same ETag as the ETag you specified. If the ETags match, then the item hasn't changed, and the server returns either an HTTP 304 Not Modified status code or an HTTP 412 Precodition Failed status code. Both of those status codes indicate that the item you've already retrieved is up-to-date.

If the ETags don't match, then the item has been modified since the last time you requested it, and the server returns the item.

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

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, spreadsheet, presentation, folder, etc.) 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.

Retrieving all documents and folders

A list of all documents and folders can be retrieved by using the showfolders parameter on the documents list feed:

GET /feeds/default/private/full?showfolders=true

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

Retrieving all word processor documents

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

GET /feeds/default/private/full/-/document

Retrieving all spreadsheet documents

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

GET /feeds/default/private/full/-/spreadsheet

Retrieving all starred presentations

You can combine more than one category. As an example, to retrieve a list of only starred presentations, use the presentation and starred categories together:

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

Retrieving all PDFs the user has viewed

As an example, to retrieve a list of viewed PDFs, use the viewed and pdf categories together:

GET /feeds/default/private/full/-/pdf/viewed

Retrieving a list of folders

A list of only folders can be retrieved by using the folder category as follows:

GET /feeds/default/private/full/-/folder

Retrieving a list of trashed documents

A list of a user's trashed documents can be retrieved by using the trashed category as follows:

GET /feeds/default/private/full/-/trashed

To include a list of trashed documents along with normal queries results, use the showdeleted parameter:

GET /feeds/default/private/full?showdeleted=true

Retrieving only shared documents

A list of PDFs owned by the requesting user:

GET /feeds/default/private/full/-/pdf/mine

All documents that user1@mail.com and user2@gmail.com are collaborating on:

GET /feeds/default/private/full?writer=user1%40gmail.com%2Cuser2%40example.com

Performing title queries

You can search for documents matching an exact title or portion of a title by using the title-exact and title query parameters, respectively. For example, if you wanted to search for documents matching the partial title "PR Handbook", you could issue:

GET /feeds/default/private/full?title=PR+Handbook

To match a title exactly, add the title-exact parameter:

GET /feeds/default/private/full?title=PR+Handbook&title-exact=true

Please see the Documents List Data API Reference Guide for more details.

Performing a full 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/default/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.

Retrieving folder contents

To retrieve a list of documents in a particular folder, send an HTTP GET to the folder's feed URL:

http://docs.google.com/feeds/default/private/full/folder%3Afolder_id/contents

By default, folder entries will also be returned within the folders feed (e.g. you don't have to include the showfolders=true parameter. The folders feed can also be queried using the query parameters defined in the Documents List Data API Reference Guide.

Entries in the folder feed might look something like the following:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns:docs="http://schemas.google.com/docs/2007" xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005"
    gd:etag="W/&quot;DkQDQH4_eSt7ImA9WxNTEkw.&quot;">
<id>http://docs.google.com/feeds/default/private/full/folder%3A0B9kQ4KIBsdfYzNmNiMjI4N/contents</id>
<updated>2009-08-14T01:46:11.041Z</updated>
<title>Available Documents - user@gmail.com</title>
<link rel="alternate" type="text/html" href="http://docs.google.com/#folders/folder.0.0B9kQ4KIBsdfYzNmNiMjI4N"/>
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml"
    href="http://docs.google.com/feeds/default/private/full/folder%3A0B9kQ4KIBsdfYzNmNiMjI4N/contents"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
    href="http://docs.google.com/feeds/default/private/full/folder%3A0B9kQ4KIBsdfYzNmNiMjI4N/contents"/>
<link rel="http://schemas.google.com/g/2005#batch" type="application/atom+xml"
    href="http://docs.google.com/feeds/default/private/full/folder%3A0B9kQ4KIBsdfYzNmNiMjI4N/contents/batch"/>
<link rel="self" type="application/atom+xml"
    href="http://docs.google.com/feeds/default/private/full/folder%3A0B9kQ4KIBsdfYzNmNiMjI4N/contents"/>
<author>
  <name>user</name>
  <email>user@gmail.com</email>
</author>
<openSearch:startIndex>1</openSearch:startIndex>
<entry gd:etag="'ERAPRDTit7ImBq'">
  <id>http://docs.google.com/feeds/id/spreadsheet%3A0AtkQLCU4Kem5sZy1WdXc</id>
  <published>2009-06-22T21:48:34.779Z</published>
  <updated>2009-07-01T04:37:49.031Z</updated>
  <app:edited xmlns:app="http://www.w3.org/2007/app">2009-07-15T21:56:17.709Z</app:edited>
  <category scheme="http://schemas.google.com/g/2005/labels"
      term="http://schemas.google.com/g/2005/labels#viewed" label="viewed"/>
  <category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#spreadsheet" label="spreadsheet"/>
  <title>Spreadsheet Title</title>
  <content type="text/html" src="http://spreadsheets.google.com/feeds/download/spreadsheets/Export?key=0AtkQLCU4Kem5sZy1WdXc"/>
  <link rel="http://schemas.google.com/docs/2007#parent" type="application/atom+xml"
      href="http://docs.google.com/feeds/default/private/full/folder%3A0B9kQ4KIBsdfYzNmNiMjI4N" title="Folder1"/>
  <link rel="http://schemas.google.com/docs/2007#parent" type="application/atom+xml"
      href="http://docs.google.com/feeds/default/private/full/folder%3A0B9kQLCiMjI4N2Y2" title="Folder2"/>
  <link rel="alternate" type="text/html" href="http://spreadsheets.google.com/ccc?key=0AtkQLCU4Kem5sZy1WdXc&amp;hl=en"/>
  <link rel="http://schemas.google.com/spreadsheets/2006#worksheetsfeed" type="application/atom+xml"
      href="http://spreadsheets.google.com/feeds/worksheets/0AtkQLCU4KkljLTdOem5sZy1WdXc/private/full"/>
  <link rel="http://schemas.google.com/spreadsheets/2006#tablesfeed" type="application/atom+xml"
      href="http://spreadsheets.google.com/feeds/0AtkQLCU4KkljLTdOem5sZy1WdXc/tables"/>
  <link rel="self" type="application/atom+xml"
   href="http://docs.google.com/feeds/default/private/full/folder%3A0B9kQLCiMjI4N2Y2/contents/spreadsheet%3A0AtkQLCU4Kem5sZy1WdXc"/>
  <link rel="edit" type="application/atom+xml"
   href="http://docs.google.com/feeds/default/private/full/folder%3A0B9kQLCiMjI4N2Y2/contents/spreadsheet%3A0AtkQLCU4Kem5sZy1WdXc"/>
  <link rel="edit-media" type="text/html" href="http://docs.google.com/feeds/default/media/spreadsheet%3A0AtkQLCU4Kem5sZy1WdXc"/>
  <author>
    <name>user</name>
    <email>user@gmail.com</email>
  </author>
  <gd:resourceId>spreadsheet:0AtkQLCU4Kem5sZy1WdXc</gd:resourceId>
  <gd:lastModifiedBy>
    <name>user</name>
    <email>user@gmail.comm</email>
  </gd:lastModifiedBy>
  <gd:lastViewed>2009-07-15T21:56:17.631Z</gd:lastViewed>
  <gd:quotaBytesUsed>0</gd:quotaBytesUsed>
  <docs:writersCanInvite value="true"/>
  <gd:feedLink rel="http://schemas.google.com/acl/2007#accessControlList"
      href="http://docs.google.com/feeds/default/private/full/spreadsheet%3A0AtkQLCU4Kem5sZy1WdXc/acl"/>
  <gd:feedLink rel="http://schemas.google.com/docs/2007/revisions"
      href="http://docs.google.com/feeds/default/private/full/spreadsheet%3A0AtkQLCU4Kem5sZy1WdXc/revisions"/>
</entry>
...
</feed>

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:

The Atom entry <atom:title> if present
The HTTP Slug header value if present. This value should be percent encoded.
A default filename chosen by Google Documents

A list of accepted file upload formats can be found here.

Uploading document content 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/default/private/full HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 73612
Content-Type: multipart/related; boundary=END_OF_PART
Slug: test.doc
--END_OF_PART
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:docs="http://schemas.google.com/docs/2007">
  <category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#document"/>
  <title>example document</title>
  <docs:writersCanInvite value="false" />
</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.

Note: The previous example includes the optional <docs:writersCanInvite> setting, which prevents collaborators from sharing the document with others. writersCanInvite can be included when creating or updating a document. In the case of an update, the previous value is retained if the tag is omitted. Possible values are "true", "false" (case sensitive), "1", or "0" (1=true, 0=false). Only the owner of a document can change the writersCanInvite setting.

Uploading document content (no metadata)

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

POST /feeds/default/private/full HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
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.

Creating an empty document with metadata (no content)

Here is an example of creating a document by uploading metadata to the server with an HTTP POST request. This will create an empty document called new document on Google Documents.

POST /feeds/default/private/full HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Content-Length: 287
Content-Type: application/atom+xml

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

Uploading a document to a folder

The same methodology can be used to upload a document to a particular folder. Send and HTTP POST request to the folders feed and reference the folder ID you wish to upload to.

This example creates an empty presentation called new preso in the folder referenced by folder_id.

POST /feeds/default/private/full/folder%3Afolder_id/contents HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 292
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#presentation"/>
  <title>new preso</title>
</entry>

Updating documents

To update an existing document, first you retrieve the document you want to update, then you modify it as desired, and then you send a PUT request to either the edit link or the edit-media link, depending on what is to be updated.

You can update any of the following:

The document's metadata
The document's contents
Both metadata and contents at once (using a MIME multipart request)

The following sections describe how to perform each of those types of update.

The new document contents, which form part of the MIME multipart request, must have a content-type for which conversion is supported--for instance, to update a Google Docs document with new content, it could have content-type application/msword, or content-type text/plain, but not content-type application/vnd.ms-excel. When updating a Google Docs spreadsheet, however, content-type application/vnd.ms-excel would be appropriate. Content-types which are not supported by the document type being updated will result in an HTTP 400 Bad Request response.

Note: For more information, see the complete list of accepted formats.

To make sure that your update doesn't overwrite another client's changes, include the original entry's ETag value. You can do this by providing the ETag value in an HTTP If-Match header, or by including the original entry's gd:etag attribute in the updated entry. To determine the original document's ETag value, examine the <entry> element's gd:etag attribute. For media entries, the ETag of the media may be available in the gd:etag attribute of the edit-media link.

If you want to update the document regardless of whether someone else has updated it since you retrieved it, then use If-Match: * and don't include the ETag.

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

Updating a document's metadata

Here is an example of updating a spreadsheet's metadata, but leaving its content unchanged. The spreadsheet's name will be changed to example spreadsheet, and collaborators will be allowed to share the document with users. Since the request does not contain new document content, the edit link is used.

PUT /feeds/default/private/full/spreadsheet%3Aspreadsheet_id
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 292
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:docs="http://schemas.google.com/docs/2007"
    xmlns:gd="http://schemas.google.com/g/2005" gd:etag="BxAaTxRZAyp7ImBq">
  <category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#spreadsheet"/>
  <title>example spreadsheet</title>
  <docs:writersCanInvite value="true" />
</entry>

Note: The writersCanInvite setting is optional.

Updating a document's content

Here is an example of changing the content of a document, but leaving its metadata unchanged. The document's name will stay the same, but its contents will be replaced with the contents of word document test.doc. Since the request contains new document content, the edit-media link is used.

PUT /feeds/default/media/document%3Adocument_id
Host: docs.google.com
GData-Version: 3.0
If-Match: <ETag or * here>
Authorization: <your authorization header here>
Content-Length: 70581
Content-Type: application/msword
Slug: test.doc

... doc contents here ...

Updating metadata and content

Here is an example of updating both the document's metadata and its content at the same time. The document's name will be updated to example document and its contents will be replaced with the contents of the Microsoft Word document test.doc. Since the request contains new document content, the edit-media link is used.

Note that including the ETag for the metadata provides an implicit If-Match for the media content as well, because any update to the media content causes the metadata's ETag to change.

PUT /feeds/default/media/document%3Adocument_id
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 73612
Content-Type: multipart/related; boundary="END_OF_PART"
Slug: test.doc
--END_OF_PART
Content-Type: application/atom+xml

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

--END_OF_PART
Content-Type: application/msword

... doc contents here ...

--END_OF_PART

In all of these cases, a successful update will return an HTTP 200 OK status code with an <atom:entry> describing the document on the server.

Deleting documents and folders

To put a document or folder in the trash, first you retrieve the entry for the document or folder, then send a DELETE request to the entry's edit URL. This is the same URL used to update the document.

Trashing a document or folder

Trashing a document or folder moves the object to the trash.

DELETE /feeds/default/private/full/resource_id HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
If-Match: <ETag or * here>
Authorization: <your authorization header here>

If the document was deleted successfully, the server responds with an HTTP 200 OK.

If you want to make sure that you don't delete a document that has been changed by another client since you retrieved it, include an HTTP If-Match header that contains the original entry's ETag value. You can determine the original entry's ETag value by examining the <entry> element's gd:etag attribute.

If you want to delete the document regardless of whether someone else has updated it since you retrieved it, then use If-Match: * and don't include the ETag. (In this case, you don't need to retrieve the entry before deleting it.)

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

Deleting a document or folder

Deleting a document or folder permanently removes the object from the user's documents list. The process for deleting a document is similar to trashing a document, just include the delete=true parameter.

DELETE /feeds/default/private/full/resource_id?delete=true HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
If-Match: <ETag or * here>
Authorization: <your authorization header here>

If the document or folder was deleted successfully, the server responds with an HTTP 200 OK.

Downloading Documents

Once you have a document's <gd:resourceId>, you can download the file in a variety of formats.

Important: If you wish to use the same OAuth/AuthSub token to download all types of documents, request a multi-scoped token good for the domains docs.google.com, spreadsheets.google.com, and docs.googleusercontent.com. For example, the AuthSub/OAuth scope parameter would be: scope=http://docs.google.com/feeds/%20http://spreadsheets.google.com/feeds/%20http://docs.googleusercontent.com/

The document's export link can be found in each entry under the <content> node, along with the document's mime-type:

<content type="text/html" src="http://docs.google.com/feeds/download/documents/Export?docID=resource_id"/>

By default, documents native to Google Docs (e.g. presentations, spreadsheets, and documents) will be exported as HTML. You may use the exportFormat parameter (described below) to export the document in an alternate format. Other types of documents such as PDFs will have a different looking export URL than the ones described below.

Exporting Documents and Presentations

Documents are accessible via the following URL:

GET /feeds/download/documents/Export?docID=resource_id&exportFormat=format

If the download request is sucessful, an HTTP 200 is returned and the file is served in the requested format.

Valid Formats for Documents

When downloading documents, the exportFormat parameter controls the format of the output. Valid values for this parameter appear below.

exportFormat Parameter Value	Format of the returned Document
`doc`	Microsoft Word
`html`	HTML Format
`odt`	Open Document Format
`pdf`	Portable Document Format
`png`	Portable Networks Graphic Image Format
`rtf`	Rich Format
`txt`	TXT File
`zip`	ZIP archive. Contains the images (if any) used in the document and an exported .html file.

Presentations are accessible via the following URL:

GET /feeds/download/presentations/Export?docID=resource_id&exportFormat=format

If the download request is sucessful, an HTTP 200 is returned and the file is served in the requested format.

Valid Formats for Presentations

Presentation formats are also controlled via the exportFormat parameter. Valid values for this parameter appear below.

exportFormat Parameter Value	Format of the returned Presentation
`pdf`	Portable Document Format
`png`	Portable Networks Graphic Image Format
`ppt`	Powerpoint Format
`swf`	Flash Format
`txt`	TXT file

Exporting Spreadsheets

Spreadsheets can be downloaded via the following URL:

GET /feeds/download/spreadsheets/Export?key=resource_id&exportFormat=format

If the download request is successful, an HTTP 200 is returned and the file is served in the requested format.

Note: The server to use when downloading spreadsheets is http://spreadsheets.google.com (as opposed to http://docs.google.com). Therefore the previous GET request would be sent to: http://spreadsheets.google.com/feeds/download/spreadsheets/Export?key=resource_id&exportFormat=format.

Valid Formats for Spreadsheets

When downloading spreadsheets, value of the exportFormat parameter controls the format of the output. Valid values for this parameter appear below:

exportFormat Parameter Value	Format of the returned Spreadsheet
`xls`	XLS (Microsoft Excel)
`csv`	CSV (Comma Seperated Value)
`pdf`	PDF (Portable Document Format)
`ods`	ODS (Open Document Spreadsheet)
`tsv`	TSV (Tab Seperated Value)
`html`	HTML Format

Exporting a single worksheet

When requesting a CSV, TSV, PDF, or HTML file you may specify an additional (optional) parameter called gid which indicates which grid, or sheet, you wish to export (the index is 0 based, so gid 1 actually refers to the second sheet sheet on a given spreadsheet). If left unspecified, the first sheet will be exported for these formats. In the case of a PDF, the whole document will be exported.

Here is an example request for a CSV representation of the second sheet in a spreadsheet:

GET http://spreadsheets.google.com/feeds/download/spreadsheets/Export?key=resource_id&exportFormat=csv&gid=1

Downloading PDFs

Native PDF files cannot be exported in a format other than .pdf. It is also not possible to manually contruct the download URL for these types of files. Instead, send an authenticated HTTP GET to the entry's <content> src link:

<content type="text/html" src="http://doc-04-20-docs.googleusercontent.com/docs/secure/m7an0emtau/WJm.../YzI2Y2ExYWVm?h=16655626&e=download&gd=true"/>

Note: The server to use when downloading PDFs is http://docs.googleusercontent.com (as opposed to http://docs.google.com). Therefore make sure to request a multi-scoped AuthSub/OAuth token that is also valid for http://docs.googleusercontent.com. See the note in the Downloading Documents section.

Creating folders

Creating a folder

To create a folder, send an HTTP POST request with an <atom:entry> containing a category element with http://schemas.google.com/g/2005#kind scheme and http://schemas.google.com/docs/2007#folder term. The folder name will be determined by the value of the atom:title element if present. If no atom:title element is submitted, a default name will be chosen.

Here is an example of creating a folder which will be called Example Folder on Google Documents.

POST /feeds/default/private/full HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 245
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#folder"/>
  <title>Example Folder</title>
</entry>

If the request is successful, a 201 Created response will be returned along with a <atom:entry> describing the folder on the server.

Creating a subfolder

Creating a subfolder is similar to creating a top-level folder. Instead of creating a document type, specify folder as the kind. This example creates a new subfolder named new subfolder under the parent folder with id folder_id.

POST /feeds/default/private/full/folder%3Afolder_id/contents HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 244
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <category scheme="http://schemas.google.com/g/2005#kind"
      term="http://schemas.google.com/docs/2007#folder"/>
  <title>new subfolder</title>
</entry>

Moving documents and folders

Documents and folders can be moved in and out of folders via the folders feed.

Moving a resource into a folder

To either move a document into a folder or to move a folder into another folder, send an HTTP POST request to the feed of the destination folder. The feed URL will have the folder ID represented by destination_folder_id in the example below. The request should contain an <atom:entry> with the document's <atom:id> you want to move.

Note: If no <atom:id> is provided in the request body's <atom:entry>, a new document will be created in the folder.

POST /feeds/default/private/full/folder%3Adestination_folder_id/contents HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 180
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id</id>
</entry>

The entry is a word processor document with id document_id.

Moving a resource out of a folder

To move a document or folder out of a folder, sent an HTTP DELETE request to the destination folder's edit link. The edit link will have a folder id and a document id, represented by folder_id and document_id respectively in the example below.

DELETE /feeds/default/private/full/folder%3Afolder_id/contents/document%3Adocument_id
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>

Moving a folder into another folder

To move a folder into a different folder, send an HTTP POST request to the destination folder's edit link. The body of the request should contain an <atom:entry> that references the <atom:id> of the folder you wish to move.

This example moves the folder source_folder_id to folder destination_folder_id.

POST /feeds/default/private/full/folder%3Adestination_folder_id/contents HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 183
Content-Type: application/atom+xml

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://docs.google.com/feeds/default/private/full/folder%3Asource_folder_id</id>
</entry>

Back to top

Modifying Document and Folder Sharing Permissions

Overview of Sharing (ACLs)
Document and folder sharing is controlled via the access control list feed. Access control lists are
just basic lists that show who has access to a given resource. In the ACL feed, we have the following roles for a given document or folder:

  owner — the owner of the document. As an owner you have the ability to modify the ACL feed, delete the document, etc.
  writer — a collaborator.
  reader — a viewer (equivalent to read-only access).

Note: Please note that the accepted values for each role are case-sensitive.
Also note that you cannot change the 'owner' role for a document.
The API supports sharing permissions on multiple levels.  These values correspond to the <gAcl:scope> type attribute:

  user — a user's email address.
  group — a Google Group email address.
  domain — a Google Apps domain.



Retrieving the ACL feed
The ACL feed can be retrieved by acessing the <gd:feedLink> element of an entry with
'rel' attribute http://schemas.google.com/acl/2007#accessControlList.
Please note that you must use the full projection to receive 'gd' specific extension elements in your
Documents List feed.
GET /feeds/default/private/full/resource_id/acl HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>

This feed will contain an <entry> element for each ACL entry that exists for the given document.
The XML snippet below shows the ACL feed for the example document. Note that the feed contains three ACL entries.
The <id> element of each ACL entry ends with the email address of the specific user that the ACL entry corresponds to:
  
    document.owner@example.com — the ACL entry for the document's owner
    a.writer@example.com — the ACL entry for a collaborator
    a.reader@example.com — the ACL entry for a reader
  
<?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:gAcl='http://schemas.google.com/acl/2007'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"CUUNSXYyfCp7ImA9WxRVGUo."'>
  <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl</id>
  <updated>2008-09-03T22:03:04.733Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule' />
  <title type='text'>Document Permissions</title>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
  href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl' />
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
  href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl' />
  <link rel='self' type='application/atom+xml'
  href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl' />
  <openSearch:totalResults>3</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <entry gd:etag='W/"CUUNSXYyfCp7ImA9WxRVGUo."'>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Adocument.owner%40example.com</id>
    <updated>2008-09-03T22:03:04.756Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule' />
    <title type='text'>Document Permission - document.owner@example.com</title>
    <link rel='self' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Adocument.owner%40example.com' />
    <link rel='edit' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Adocument.owner%40example.com' />
    <gAcl:role value='owner' />
    <gAcl:scope type='user' value='document.owner@example.com' />
  </entry>
  <entry gd:etag='W/"CUMFQnc4fip7ImA9WxRVGUo."'>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aa.writer%40example.com<>
    <updated>2008-09-03T22:03:04.762Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule' />
    <title type='text'>Document Permission - a.writer@example.com</title>
    <link rel='self' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aa.writer%40example.com' />
    <link rel='edit' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aa.writer%40example.com' />
    <gAcl:role value='writer' />
    <gAcl:scope type='user' value='a.writer@example.com' />
  </entry>
  <entry gd:etag='W/"CUMASXg8fCp7ImA9WxRVGUo."'>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aa.reader%40example.com</id>
    <updated>2008-09-03T22:03:04.763Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule' />
    <title type='text'>Document Permission - a.reader@example.com</title>
    <link rel='self' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aa.reader%40example.com' />
    <link rel='edit' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aa.reader%40example.com' />
    <gAcl:role value='reader'/>
    <gAcl:scope type='user' value='a.reader@example.com' />
  </entry>
</feed>


Modifying the ACL feed
The ACL feed accepts GET, POST and PUT requests. To insert a new role into the ACL feed,
simply issue a POST request.

The example below shows how to share a document with a single collaborator:
POST /feeds/default/private/full/resource_id/acl HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/acl/2007#accessRule'/>
  <gAcl:role value='writer'/>
  <gAcl:scope type='user' value='new_writer@example.com'/>
</entry>

The new entry is returned on a successful insertion:
201 Created

<entry gd:etag='W/"CUUNSXYyfCp7ImA9WxRVGUo."'>
  <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Anew_writer%40example.com</id>
  <updated>2008-09-11T03:10:00.913Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
        term='http://schemas.google.com/acl/2007#accessRule'/>
  <title type='text'>Document Permission - new_writer@example.com</title>
  <link rel='self' type='application/atom+xml'
        href='http://docs.google.com/feeds/acl/private/full/document%3Adocument_id/acl/user%3Anew_writer%40example.com'/>
  <link rel='edit' type='application/atom+xml'
        href='http://docs.google.com/feeds/acl/private/full/document%3Adocument_id/acl/user%3Anew_writer%40example.com'/>
  <gAcl:role value='writer'/>
  <gAcl:scope type='user' value='new_writer@example.com'/>
</entry>


Sharing a folder
To share a folder, simply provide a folder resource ID instead of a document ID.  This example grants everyone
on the domain example.com the ability to read the folder's content:
POST /feeds/default/private/full/folder%3Afolder_id/acl HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>

<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:gAcl='http://schemas.google.com/acl/2007'>
<category scheme='http://schemas.google.com/g/2005#kind'
           term='http://schemas.google.com/acl/2007#accessRule'/>
<gAcl:role value='reader'/>
<gAcl:scope type='domain' value='example.com'/>
</entry>

Note: All child objects of the folder reflect will reflect the new sharing permission.

Group and Domain level sharing
Similar to sharing with a single user, you can share documents or folders across a Group or domain if you
have a Google Apps domain.
Sharing to a group email address:
<gAcl:scope type="group" value="group@example.com"/>
Sharing to an entire domain:
<gAcl:scope type="domain" value="example.com"/>
Note: Certain sharing ACLs may only be possible if the domain is configured
to allow such permissions (e.g. if sharing outside of the domain for Google Apps domains is enabled, etc).

Updating sharing permissions
To update the entry, we will need to issue an HTTP PUT request to the entry's edit link, which is simply
a <link> element, whose 'rel' attribute is set to 'edit'. In our case it is:
<link rel='edit'
      type='application/atom+xml'
      href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Anew_writer%40example.com'/>
The snippet below changes the entry's role to that of a 'reader':
PUT /feeds/default/private/full/document%3Adocument_id/acl/user%3Anew_writer%40example.com HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'
       xmlns:gd='http://schemas.google.com/g/2005'
       gd:etag='W/"CUUNSXYyfCp7ImA9WxRVGUo."'>
  <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/>
  <gAcl:role value='reader'/>
  <gAcl:scope type='user' value='new_writer@gmail.com'/>
</entry>


Removing sharing permissions
To remove permissions for this user, issue a DELETE request to the same edit link that was used for the PUT request:
DELETE /feeds/default/private/full/resource_id/acl/user%3Anew_writer%40example.com HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>

HTTP/1.1 200 OK


Batching ACL requests
Batch processing gives you the ability to execute multiple operations in one request, rather than submitting each operation individually. 
The server will perform as many of the requested changes as possible and return status information that you can use to evaluate the success or failure of each operation. For more details about batch processing in Google Data API, see Batch Processing with Google Data APIs
In a batch ACL feed, every operation has an <id> element except for insert operations. This element is the same as the request URL used in updating, deleting or querying a document ACL. It is used to identify the target entry. New entries do not have <id> elements as they have not been created yet. You can instead define a string value in  <batch:id>, which will be returned in the server's response and used to look up the corresponding entry.
The example below shows how to query, insert, update and delete users of a document:
POST /feeds/default/private/full/resource_id/acl/batch HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'
      xmlns:batch='http://schemas.google.com/gdata/batch'>
  <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/>
  <entry>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aowner%40example.com</id>
    <batch:operation type="query"/>
  </entry>
  <entry>
    <batch:id>1</batch:id>
    <batch:operation type='insert'/>
    <gAcl:role value='writer'/>
    <gAcl:scope type='user' value='new_writer@example.com'/>
  </entry>
  <entry>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aold_writer%40example.com</id>
    <batch:operation type='update'/>
    <gAcl:role value='reader'/>
    <gAcl:scope type='user' value='old_writer@example.com'/>
  </entry>
  <entry>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Adeprecated_writer%40example.com</id>
    <batch:operation type='delete'/>
    <gAcl:role value='writer' />
    <gAcl:scope type='user' value='deprecated_writer@example.com' />
  </entry>
</feed>

The returned feed will contain one result entry for each operation:
 
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns:atom='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
      xmlns:gAcl='http://schemas.google.com/acl/2007' xmlns:batch='http://schemas.google.com/gdata/batch'>
  <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl</id>
  <updated>2009-03-06T09:13:23.382Z</updated>
  <title type='text'>Batch Feed</title>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl'/>
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
    href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/batch'/>
  <entry>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aowner%40example.com</id>
    <updated>2009-03-06T09:13:23.381Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/>
    <title type='text'>Document Permission - owner@example.com</title>
    <link rel='self' type='application/atom+xml'
      href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aowner%40example.com'/>
    <link rel='edit' type='application/atom+xml'
      href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aowner%40example.com'/>
    <gAcl:role value='owner'/>
    <gAcl:scope type='user' value='owner@example.com'/>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='query'/>
  </entry>
  <entry>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Anew_writer%40example.com</id>
    <updated>2009-03-06T09:13:25.381Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/>
    <title type='text'>Document Permission - new_writer@example.com</title>
    <link rel='self' type='application/atom+xml'
      href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Anew_writer%40example.com'/>
    <link rel='edit' type='application/atom+xml'
      href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Anew_writer%40example.com'/>
    <gAcl:role value='writer'/>
    <gAcl:scope type='user' value='new_writer@example.com'/>
    <batch:id>1</batch:id>
    <batch:status code='201' reason='Created'/>
    <batch:operation type='insert'/>
  </entry>
  <entry>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aold_writer%40example.com</id>
    <updated>2009-03-06T09:13:27.737Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/acl/2007#accessRule'/>
    <title type='text'>Document Permission - old_writer@example.com</title>
    <link rel='self' type='application/atom+xml'
      href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aold_writer%40example.com'/>
    <link rel='edit' type='application/atom+xml'
      href='http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aold_writer%40example.com'/>
    <gAcl:role value='reader'/>
    <gAcl:scope type='user' value='old_writer@example.com'/>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='update'/>
  </entry>
  <entry>
    <id>http://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Adeprecated_writer%40example.com</id>
    <updated>2009-03-06T09:13:29.743Z</updated>
    <title type='text'>Deleted</title>
    <content type='text'>Deleted</content>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='delete'/>
  </entry>
</feed>



Back to top

Document Revisions

Retrieving document revisions
Document revisions are available via the revisions feed.  Similar to an <gd:feedLink> for ACLs, every
document entry will have a <gd:feedLink> pointing to the revisions feed:
<gd:feedLink rel="http://schemas.google.com/docs/2007/revisions"
    href="http://docs.google.com/feeds/default/private/full/resource_id/revisions"/>

To fetch the revision history for a document, send an HTTP GET to the <gd:feedLink> with
'rel' attribute equal to http://schemas.google.com/docs/2007/revisions:
GET /feeds/default/private/full/resource_id/revisions HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns:batch="http://schemas.google.com/gdata/batch" xmlns:gd="http://schemas.google.com/g/2005"
    gd:etag="W/&quot;CE4HQX08cCt7ImA9WxNTFEU.&quot;">
<id>http://docs.google.com/feeds/default/private/full/resource_id/revisions</id>
<updated>2009-08-17T04:22:10.378Z</updated>
<title>Document Revisions</title>
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml"
    href="http://docs.google.com/feeds/default/private/full/resource_id/revisions"/>
<link rel="http://schemas.google.com/g/2005#batch" type="application/atom+xml"
    href="http://docs.google.com/feeds/default/private/full/resource_id/revisions/batch"/>
<link rel="self" type="application/atom+xml"
    href="http://docs.google.com/feeds/default/private/full/resource_id/revisions"/>
<openSearch:totalResults>6</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<entry>
  <id>http://docs.google.com/feeds/id/resource_id/revisions/0</id>
  <updated>2009-08-17T04:22:10.440Z</updated>
  <app:edited xmlns:app="http://www.w3.org/2007/app">2009-08-06T03:25:07.798Z</app:edited>
  <title>Revision 0</title>
  <content type="text/html" src="http://docs.google.com/feeds/download/documents/Export?docId=doc_id&amp;revision=0"/>
  <link rel="alternate" type="text/html"
      href="http://docs.google.com/Doc?id=doc_id&amp;revision=0"/>
  <link rel="self" type="application/atom+xml"
      href="http://docs.google.com/feeds/default/private/full/resource_id/revisions/0"/>
  <author>
    <name>user</name>
    <email>user@gmail.com</email>
  </author>
</entry>
<entry>
  <id>http://docs.google.com/feeds/id/resource_id/revisions/1</id>
  <updated>2009-08-17T04:22:10.440Z</updated>
  <app:edited xmlns:app="http://www.w3.org/2007/app">2009-08-06T03:25:07.799Z</app:edited>
  <title>Revision 1</title>
  <content type="text/html" src="http://docs.google.com/feeds/download/documents/Export?docId=doc_id&amp;revision=1"/>
  <link rel="alternate" type="text/html"
      href="http://docs.google.com/Doc?id=doc_id&amp;revision=1"/>
  <link rel="self" type="application/atom+xml"
      href="http://docs.google.com/feeds/default/private/full/resource_id/revisions/1"/>
  <author>
    <name>user</name>
    <email>user@gmail.com</email>
  </author>
</entry>
<entry>
  <id>http://docs.google.com/feeds/id/resource_id/revisions/2</id>
  <updated>2009-08-17T04:22:10.440Z</updated>
  <app:edited xmlns:app="http://www.w3.org/2007/app">2009-08-14T07:11:34.197Z</app:edited>
  <title>Revision 2</title>
  <content type="text/html" src="http://docs.google.com/feeds/download/documents/Export?docId=doc_id&amp;revision=2"/>
  <link rel="alternate" type="text/html"
      href="http://docs.google.com/Doc?id=doc_id&amp;revision=2"/>
  <link rel="self" type="application/atom+xml"
      href="http://docs.google.com/feeds/default/private/full/resource_id/revisions/2"/>
  <author>
    <name>another_user</name>
    <email>another_user@gmail.com</email>
  </author>
</entry>
</feed>


Properties of a revision entry:


  The <updated> field is the timestamp a revision was created.
  The <author> field is the creator of that revision.


Note: While document and presentation revisions have an autoincrementing revision number, this may have gaps if revisions are deleted so
you should not rely on a sequencial sequence.  Spreadsheet revisions look almost identical, but their revision ids are not zero based and auto-incrementing -
instead they are based on the revision's timestamp, and so they will be an increasing series of random-looking numbers

Downloading a revision

The <content> field's 'src' attribute can be used to Export a particular revision in the API's supported exportFormats:

<content type="text/html" src="http://docs.google.com/feeds/download/documents/Export?docId=doc_id&revision=2"/>


For example, to download 'Revision 2' of from the XML above, you would send an HTTP GET as such:
GET /feeds/download/documents/Export?docId=doc_id&revision=2 HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>


Note: You will need a valid AuthSub/OAuth or ClientLogin token valid for the appropriate service.  See downloading documents.

Back to top

Special Features

Optical Character Recognition (OCR)

Optical Character Recognition, OCR gives your application the ability
to convert high-resolution image files containing typewritten/printed text, into editable text. As an example, you could use this feature to upload scanned
letters or old faxes to Google Docs. The server will attempt to extract the text from the images; creating a new Google Doc for each image.

Important: Keep in mind that this is still an experimental feature. We will continue to improve latency and
formatting preservation. There is also a quota in place to use this service. If you start receiving 403 errors,
you've likely hit the limit. There is a significantly higher quota in place for premier Google Apps users.

Limitations:

Supported image formats: image/jpeg, image/png, image/gif
Works best with high resolution images (at least 10 pixel character height)
OCR is a computationally expensive operation and can take up to 30 seconds.
Works only for latin character sets.


To perform OCR on a .jpg, .png, or .gif file, include the ocr=true parameter when uploading a file:
POST /feeds/default/private/full?ocr=true HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 1984
Content-Type: image/png
Slug: OCRd Doc

... png contents here ...


Document Translation

When uploading a document, you can (optionally) translate the text into another language by specifying the
targetLanguage=x and sourceLanguage=y parameters. Google will attempt to autodetect the sourceLanguage if one is not provided.
Generally, the auto detection works well, but if it fails, an error will be returned to your client. Note also that not all translation pairs are viable
(e.g. Estonian to Chinese). If you attempt to use an supported pair, an error message will be returned.

This example will attempt to translate the user's .doc file from English to German and store the result as a Google Doc:
POST /feeds/default/private/full/?sourceLanguage=en&targetLanguage=de HTTP/1.1
Host: docs.google.com
GData-Version: 3.0
Authorization: <your authorization header here>
Content-Length: 5175
Content-Type: application/msword
Slug: Going Multilingual

... doc contents here ...


A full list of supported can be found by opening the "Tools > Translate Document" menu in Google Docs.
Viable country codes can be found here.

Back to top

Faster apps faster - GWT 2.0 with Speed Tracer New!

Google Documents List Data API v3.0 (Labs)

Documents List Data API

Google Data Protocol

Protocol Guide (v3.0)

Contents

Audience

Authenticating to the Documents service

AuthSub for web applications

Upgrading to a session token

OAuth for web applications

Example request

ClientLogin for installed/mobile applications

Need more information on authorization?

Specifying a version

Retrieving a list of documents

Document resource ID

Retrieving a list or resource again

Searching the documents feed

Retrieving all documents and folders

Retrieving all word processor documents

Retrieving all spreadsheet documents

Retrieving all starred presentations

Retrieving all PDFs the user has viewed

Retrieving a list of folders

Retrieving a list of trashed documents

Retrieving only shared documents

Performing title queries

Performing a full text query

Retrieving folder contents

Uploading documents

Uploading document content with metadata

Uploading document content (no metadata)

Creating an empty document with metadata (no content)

Uploading a document to a folder

Updating documents

Updating a document's metadata

Updating a document's content

Updating metadata and content

Deleting documents and folders

Trashing a document or folder

Deleting a document or folder

Downloading Documents

Exporting Documents and Presentations

Valid Formats for Documents

Valid Formats for Presentations

Exporting Spreadsheets

Valid Formats for Spreadsheets

Exporting a single worksheet

Downloading PDFs

Creating folders

Creating a folder

Creating a subfolder

Moving documents and folders

Moving a resource into a folder

Moving a resource out of a folder

Moving a folder into another folder

Modifying Document and Folder Sharing Permissions

Overview of Sharing (ACLs)

Retrieving the ACL feed

Modifying the ACL feed

Sharing a folder

Group and Domain level sharing

Updating sharing permissions

Removing sharing permissions

Batching ACL requests

Document Revisions

Retrieving document revisions

Downloading a revision

Special Features

Optical Character Recognition (OCR)

Document Translation

Faster apps faster - GWT 2.0 with Speed Tracer ^New!