Document

This guide introduces concepts such as the primary methods that make up the Google Docs API, how to access a document, and the workflow when creating a document.

API methods

The documents resource provides methods you use to invoke the Docs API. The following methods let you create, read, and update Docs documents:

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 Docs API requests and response methods, see Requests and responses.

Document ID

The documentId is the unique identifier for the document and it can be derived from a document's URL. It's a particular string containing letters, numbers, and some special characters. Document IDs are stable, even if the document name changes.

https://docs.google.com/document/d/DOCUMENT_ID/edit

The following regular expression can be used to extract the documentId from a Google Docs URL:

/document/d/([a-zA-Z0-9-_]+)

If you're familiar with the Google Drive API, the documentId corresponds to id in the files resource.

Manage documents in Google Drive

Docs files are stored in Google Drive, our cloud-based storage service. While Docs API has its own standalone methods, it's often necessary to also use Google Drive API methods to interact with a user's Docs files. For example, to copy Docs files, use Drive API's files.copy method. For more information, see Copy an existing document.

By default, when using the Docs API a new document is saved to the user's root folder on Drive. There are options for saving a file to a Drive folder. For more information, see Work with Google Drive folders.

Work with Docs files

To retrieve a document from a user's My Drive, it's often necessary to first use Drive's files.list method to retrieve the ID for a file. Calling the method without any parameters returns a list of all files and folders, including the IDs, for the user.

A document's MIME type indicates the data type and format. The MIME type format for Docs is application/vnd.google-apps.document. For a list of MIME types, see Google Workspace and Google Drive supported MIME types.

To search by MIME type for just Docs files within My Drive, append the following query string filter:

q: mimeType = 'application/vnd.google-apps.document'

For more information about query string filters, see Search for files and folders.

Once you know the documentId, use the documents.get method to retrieve a complete instance of the specified document. For more information, see Requests and responses.

To export Google Workspace document byte content, use Drive's files.export method with the documentId of the file to export and the correct export MIME type. For more information, see Export Google Workspace document content.

Compare the Get and List methods

The following table describes the differences between the Drive and Docs methods, and the data that's returned with each:

Operator Description Usage
drive.files.get Gets a file's metadata by ID. Returns an instance of the files resource. Get the metadata for a specific file.
drive.files.list Gets a user's files. Returns a list of files. Get a list of user files when you're unsure which file you must modify.
docs.documents.get Gets the latest version of the specified document, including all formatting and text. Returns an instance of the documents resource. Get the document for a specific document ID.

Document creation 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.
Figure 1. Workflow to create and populate a new document.

In the Figure 1., a user interacting with the documents resource has the following flow of information:

  1. An app calls the documents.create method on a web server.
  2. The web server sends an HTTP response that contains an instance of the created document as a documents resource.
  3. Optionally, the app calls the documents.batchUpdate method to atomically perform a set of edit requests to populate the document with data.
  4. The web server sends an HTTP response. Some documents.batchUpdate methods provide a response body with information about the applied requests, whereas others surface an empty response.

Document update workflow

Updating an existing document is more complex. Before you can make meaningful calls to update a document, you must know its current state: what elements make it up, what content is in those elements, and the order of the elements within the document. The following sequence diagram shows how this works:

Workflow to update a document.
Figure 2. Workflow to update a document.

In the Figure 2., a user interacting with the documents resource has the following flow of information:

  1. An app calls the documents.get method on a web server, with the documentId of the file to find.
  2. The web server sends an HTTP response that contains an instance of the specified document as a documents resource. The returned JSON contains the document content, formatting, and other features.
  3. The app parses the JSON so the user can determine what content or format to update.
  4. The app calls the documents.batchUpdate method to atomically perform a set of edit requests to update the document.
  5. The web server sends an HTTP response. Some documents.batchUpdate methods provide a response body with information about the applied requests, whereas others surface an empty response.

This diagram doesn't consider workflows where concurrent updates by other collaborators are made in the same document. For more information, see the best practices section Plan for collaboration.