This document provides detailed reference documentation for the Google Documents List Data API.

Contents

Audience

This document is intended for programmers who want to write client applications that can interact with Docs.

It's a reference document; it assumes that you understand the concepts presented in the Developer's Guide, and the general ideas behind the Google Data APIs protocol.

Document List API feeds

Google Documents List feed URI takes the following form:

http://docs.google.com/feeds/documents/visibility/projection

The visibility parameter has two possible values: private and public.

Note: Currently, private is the only visibility available in the Documents List API. For more information, see Visibility values, below.

The projection parameter indicates what information is included in the representation. For example, if your client specifies a projection of basic, it's requesting an Atom feed without any Google Data extension elements. For a list of values, see Projection values, below.

Documents list feed

The documents feed lists all the documents for the Google Account that's associated with the authenticated user:

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

When the URI includes a id value, then the feed contains only the entry for the document associated with the provided resourceID:

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

Visibility values

The following table describes the supported visibility values:

Visibility	Description	Updatability	Security Notes
private	For use whenever you can authenticate the request.	Read/write access if the authenticated user has edit privileges; otherwise, read-only.	Requires authentication.

Projection values

The following table describes the supported projection values:

Projection Name	Description	Updatability
full	Full-fidelity feed; contains all meta data information.	Full read/write access.
expandAcl	Expands the ACL feed (gd:feedLink) inline to an <atom:entry>.	Full read/write access.

Folders feed

The folders feed is used to list and manipulate a folder's contents:

http://docs.google.com/feeds/folders/private/full/resourceID

Visibility values

The following table describes the supported visibility values:

Visibility	Description	Updatability	Security Notes
private	For use whenever you can authenticate the request.	Read/write access if the authenticated user has edit privileges; otherwise, read-only.	Requires authentication.

Projection values

The following table describes the supported projection values:

Projection Name	Description	Updatability
full	Full-fidelity feed; contains all meta data information.	Full read/write access.

ACL feed

The acl feed is used to modify a document's sharing permissions:

http://docs.google.com/feeds/acl/private/full/resourceID

Visibility values

The following table describes the supported visibility values:

Visibility	Description	Updatability	Security Notes
private	For use whenever you can authenticate the request.	Read/write access if the authenticated user has edit privileges; otherwise, read-only.	Requires authentication.

Projection values

The following table describes the supported projection values:

Projection Name	Description	Updatability
full	Full-fidelity feed; contains all meta data information.	Full read/write access.

Documents List query parameters reference

Documents List supports the following standard Google Data query parameters: alt, author, q, start-index, max-results, updated-min, updated-max, /category

For more information about the standard parameters, see the Google Data APIs protocol reference document.

In addition to the standard Google Data query parameters, the Documents List Data API uses the following parameters.

Parameter	Meaning	Notes
title	Specifies the search terms for the title of a document.	This parameter used without title-exact will only submit partial queries, not exact queries.
title-exact	Specifies whether the title query should be taken as an exact string.	Meaningless without title. Possible values are true and false. Note: Matches are case-insensitive.
opened-min	Bounds on the last time a document was opened by the current user.	Use the RFC 3339 timestamp format. For example: opened-min=2005-08-09T09:57:00-08:00
opened-max	Bounds on the last time a document was opened by the current user.	Use the RFC 3339 timestamp format. For example: opened-max=2005-08-09T10:57:00-08:00
owner	Searches for documents with a specific owner.	Use the email address of the owner. For example: owner=user%40gmail.com
writer	Searches for documents which can be written to by specific users.	Use a single email address or a comma separated list of email addresses. For example: writer=user1%40gmail.com%2Cuser2%40example.com
reader	Searches for documents which can be read by specific users.	Use a single email address or a comma separated list of email addresses. For example: reader=user1%40gmail.com%2Cuser2%40example.com
showfolders	Specifies whether the query should return folders as well as documents.	Possible values are true and false. Default is false
showdeleted	Specifies whether the query should return documents which are in the trash as well as other documents.	Possible values are true and false. Default is false
append	Specifies if data should be appended to a document when updating its content.	Possible values are true and false. Default is false.
orderby	Specifies the sort order of the document list as returned by the server.	Possible values are title, starred, last-modified, last-viewed. Default is last-modified.

The Documents List data API supports the following categories.

Category	Scheme	Term	Label	Membership
Document Type	http://schemas.google.com/g/2005#kind	http://schemas.google.com/docs/2007#type	type	All documents of the corresponding type in the requesting users document list. type is currently one of: document folder pdf presentation spreadsheet
Starred Status	http://schemas.google.com/g/2005/labels	http://schemas.google.com/g/2005/labels#starred	starred	All documents that have been starred by the requesting user
Trashed Status	http://schemas.google.com/g/2005/labels	http://schemas.google.com/g/2005/labels#trashed	trashed	All documents that have been sent to the trash by the requesting user
Hidden status	http://schemas.google.com/g/2005/labels	http://schemas.google.com/g/2005/labels#hidden	hidden	All documents that are hidden
Viewed status	http://schemas.google.com/g/2005/labels	http://schemas.google.com/g/2005/labels#viewed	viewed	All documents that have been viewed by the requesting user
Owned by user	http://schemas.google.com/g/2005/labels	http://schemas.google.com/g/2005/labels#mine	mine	All documents that are owned by the requesting user
Private status	http://schemas.google.com/g/2005/labels	http://schemas.google.com/g/2005/labels#private	private	All documents that are not shared with anyone
Shared with domain	http://schemas.google.com/g/2005/labels	http://schemas.google.com/g/2005/labels#shared-with-domain	shared-with-domain	All documents that are shared with everyone at the user's hosted domain. This only works for Google Apps users.
Containing Folders	http://schemas.google.com/docs/2007/folders/user-email	folder-name	folder-name	All documents inside the given folder for the requesting user

Note that category queries can have name conflicts (eg: starred could mean a starred document or a document in a folder named starred). To ensure the desired results, it is best to use scheme qualification for your category terms when there may be a conflict. For more information about category queries see the Google Data APIs protocol reference document query documentation.

Back to top

Documents List Export

Documents are exported using the following URL:

http://docs.google.com/feeds/download/documents/Export

Presentations are exported using the following URL:

http://docs.google.com/feeds/download/presentations/Export

The following parameters when requesting exports of documents or presentations:

Parameter	Meaning	Notes
docID	Required. Specifies the document/presentation id to download.	This value can be found in the resource id. For example '12345' in <gd:resourceID>document:12345</gd:resourceID>.
exportFormat	Optional. Specifies the output format.	Values for documents: "txt", "odt", "pdf", "html", "rtf", "doc", "png", "zip" Values for presentations: "swf", "pdf", "png", and "ppt".

Spreadsheets are exported using the following URL:

http://spreadsheets.google.com/feeds/download/spreadsheets/Export

The following parameters when requesting exports of spreadsheets:

Parameter	Meaning	Notes
key	Required. Specifies the spreadsheet key/id to download.	This value can be found in the resource id. For example '12345' in <gd:resourceID>spreadsheet:12345</gd:resourceID>.
exportFormat	Optional. Specifies the output format for spreadsheets.	Valid values are "xls", "csv", "pdf", "ods", "tsv, "html"
gid	Optional. When requesting a spreadsheet output in CSV or TSV format, this parameter is required and specifies the spreadsheet page.	The spreadsheet page is based on a zero based index, so gid=1 actually refers to the second page in the spreadsheet.