)
This document provides detailed reference documentation for the Google Documents List Data API.
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.
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.
Google Documents List feed URI takes the following form:
http(s)://docs.google.com/feeds/default/visibility/full/
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.
The documents feed lists all the documents for
the Google Account that's associated with the authenticated user:
http(s)://docs.google.com/feeds/default/visibility/full/[resourceID]
Permitted HTTP operations: GET, POST, PUT, DELETE
When the URI includes an (optional) resourceID value, then the feed contains only the entry for the document associated with the provided ID.
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. |
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. |
The folders feed is used to list and manipulate a folder's contents:
http(s)://docs.google.com/feeds/default/private/full/resourceID/contents
Permitted HTTP operations: GET, POST, DELETE
In the above example, resourceID would take the form of folder%3A12345 to represent a folder ID.
The acl feed is used to modify a document's sharing permissions:
http(s)://docs.google.com/feeds/default/private/full/resourceID/acl
In the above example, resourceID represents the object you are requesting/modifying the sharing permissions for.
For example, a document would be document%3A12345, a folder would be folder%3A12345, etc.
Permitted HTTP operations: GET, POST, PUT, DELETE
The media feed is used to update a document's content body:
http(s)://docs.google.com/feeds/default/media/resourceID
In the above example, resourceID represents the object you wish to update.
For example, a document would be document%3A12345, a spreadsheet would be spreadsheet%3A12345, etc.
Permitted HTTP operations: PUT
The revisions feed is used view the :
http(s)://docs.google.com/feeds/default/private/full/resourceID/revisions/[revisionID]
In the above example, resourceID represents the object you are requesting revision history for. For example, a spreadsheet would be
spreadsheet%3A12345, a document would be document%3A12345, etc.
You may also fetch a particular revision by appending a (optional) revision ID to the end of the feed URI.
Permitted HTTP operations: GET
Documents are exported using the following URL:
http(s)://docs.google.com/feeds/download/documents/Export
Presentations are exported using the following URL:
http(s)://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(s)://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. Specifies the spreadsheet grid to export. | Only used when requesting a spreadsheet output in HTML, CSV, or TSV format. Omitting this parameter will cause the whole document to be exported (PDF). For other document types this parameter is ignored. |
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 |
Lower bound 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 |
Upper bound on the last time a document was opened by the current user. | Use the RFC 3339 timestamp format. For example: opened-max=2009-03-02T10:00:00 |
edited-min |
Lower bound on the last time a document was edited by the current user. This value corresponds to the <app:edited> value
in the Atom entry, which represents changes to the document's content or metadata. |
Use the RFC 3339 timestamp format. For example: edited-min=2005-08-09T09:57:00-08:00 |
edited-max |
Upper bound on the last time a document was edited by the user. This value corresponds to the <app:edited> value
in the Atom entry, which represents changes to the document's content or metadata. |
Use the RFC 3339 timestamp format. For example: edited-max=2009-08-09T09: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 |
ocr |
Specifies whether to attempt OCR on a .jpg, .png, of .gif upload. | Possible values are true and false. Default is false. See OCR in the Protocol Guide. |
targetLanguage |
Specifies the language to translate a document into. | See Document Translation in the Protocol Guide for a table of possible values. |
sourceLanguage |
Specifies the source language of the original document. | Optional when using the translation service. If not provided, Google will attempt to auto-detect the source language. See Document Translation in the Protocol Guide for a table of possible values. |
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:
|
| 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. |
|
