This guide introduces the primary request and response methods that make up the Google Docs API and how you can update a document in batches.
You can invoke the Google Docs API using an HTTP request, or by using a method invocation in a language-specific client library. These are broadly equivalent.
The Google Docs API returns an HTTP response, which generally includes the result of the request invocation. When using a client library to make requests, the responses are returned in a language-specific way.
Request methods
The Docs API supports the following methods:
documents.create: Create a blank Google Docs document.documents.get: Return a complete instance of the specified document. You can parse the returned JSON to extract the document content, formatting, and other features.documents.batchUpdate: Submit a list of editing requests to apply atomically to the document, and return a list of results.
The documents.get and documents.batchUpdate methods require a documentId
as a parameter to specify the target document. The documents.create method
returns an instance of the created document, from which you can read the
documentId. For more information about documentId, see Document
ID.
Note that you can't use the documents.get method to retrieve published
documents. Once published, public documents use a different URL format. Attempts
to use the URL's new documentId with the documents.get method returns a
404 HTTP status code response. There are no methods to retrieve the original
documentId from the published URL. To workaround this issue, you can use the
Drive API to copy the published
document to a shared
document and then access this file instead. For more information, see Make
Google Docs, Sheets, Slides &
Forms public.
Batch updates
The
documents.batchUpdate
method takes a list of
request objects, each one
specifying a single request to perform. For example, format a paragraph and then
add an inline image. Each request is validated before being applied and the
requests are processed according to the order they appear in the batch request.
All requests 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.
Some documents.batchUpdate methods provide responses with information about
the applied requests. These methods return a response
body that
contains a list of response
objects. Other requests don't need to return information and surface an empty
reply. The objects in the response list occupy the same index order as the
corresponding request.
A popular pattern for making batch requests looks like this:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
See batch request best practices for full details on
how to batch your Docs API calls and the
documents.batchUpdate
reference documentation for request and response types.
Batch update operations
There are various types of batch update requests. Here's a breakdown of the request types, grouped into different categories.