Introduction

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:

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:

Workflow to create and populate a new document.

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:

Workflow to update a document.

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.