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.