The Google Docs API lets you create and modify documents.
Apps can integrate with the Docs API to create polished documents from both user and system-provided data. The API allows you to:
- Automate processes
- Create documentation in bulk
- Generate invoices or contracts
Overview of the API
The documents resource provides methods you use to invoke the Docs API.
API methods
The following methods let you create, read, and update Google Docs documents:
- Use documents.create to create a document.
- Use documents.get to retrieve the contents of a specified document.
- Use documents.batchUpdate to atomically perform a set of updates on a specified document.
The get
and batchUpdate
methods require a documentId
(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.
Batch updates
The batchUpdate
method takes a list of request objects, and makes updates
according to the same order they appear in the batch request. The updates
in the batch update are applied atomically. That is, if any request isn't valid, then the entire update is unsuccessful and none of the (potentially dependent) changes are applied.
The batchUpdate
method returns a list of response objects. The objects in this
list occupy the same index order as the corresponding request.
See batch request best practices for how to batch API calls together and the batchUpdate reference documentation for the request and response types.
Document ID
Document IDs reference a document and they can be derived from the URL:
https://docs.google.com/document/d/documentId/edit
The documentId
is a unique 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:
/document/d/([a-zA-Z0-9-_]+)
If you're familiar with the Google Drive API, the documentId
corresponds to the
ID of the File
resource.
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's 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 items are located within the document. The following sequence diagram shows how this works:
This diagram doesn't consider workflows where concurrent updates by other collaborators are made in the same document. See Plan for collaboration for a discussion of this topic.