The Google Docs API lets you create and modify documents.
Apps can integrate with the Google Docs API to create polished documents from user- and system-provided data. The API allows you to do tasks such as the following:
- Automate processes
- Create documentation in bulk
- Generate invoices or contracts
Overview of the API
The documents collection provides methods that you use to invoke the Google Docs API.
The following methods let you create, read, and update Google Docs documents:
- Use documents.create to create a new document.
- Use documents.get to retrieve the entire contents of a specified document.
- Use documents.batchUpdate to atomically perform a set of updates on a specified document.
batchUpdate methods require a document ID (see below) as a
parameter to specify the target document. The
create method returns an instance
of the created document, from which you can read the ID.
batchUpdate method takes a list of request objects, and makes updates
according to those requests in the order they appear in the list. The updates
are all performed atomically: if any request in the batch fails, then none of
the updates in that batch are applied to the document, which is then left
batchUpdate method returns a list of response objects. The objects in this
list correspond 1:1 with the list of requests supplied in the call.
See the batchUpdate reference documentation for details of the request and response types.
Documents are referenced by their IDs. The ID of a document can be derived from the URL:
The document ID is a string containing letters, numbers, and some special characters. The following regular expression can be used to extract the document ID from a Google Docs URL:
If you're familiar with the Drive API, the
documentId corresponds to the
ID of the File
Locations within a document: indexes
When you make updates to the content of a document, each update takes place at a location or across a range within the document. These locations and ranges are specified using indexes, which represent an offset within a containing document segment. To learn more about indexes and how to use them, see the Structure of a Google Docs document concept guide.
Document update workflow
Creating and populating a new document is straightforward, since there is no existing content to worry about and there are no collaborators who can alter the document state. Conceptually, this works as shown in the following sequence diagram:
Updating an existing document is more complex. Before you can make meaningful calls to update a document, you need to know the current state of the document: what elements make it up, what content is in those elements, and where all these things are located within the document. The following sequence diagram shows how this works:
This diagram does not consider the issue of concurrent updates that may be made in the document by other collaborators. See Plan for collaboration for a discussion of this topic.