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:
- Use the
documents.create
method to create a document. - Use the
documents.get
method to retrieve the contents of a specified document. - Use the
documents.batchUpdate
method to atomically perform a set of updates on a specified document.
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:
In the Figure 1., a user interacting with the
documents
resource has the following
flow of information:
- An app calls the
documents.create
method on a web server. - The web server sends an HTTP response that contains an instance of the
created document as a
documents
resource. - Optionally, the app calls the
documents.batchUpdate
method to atomically perform a set of edit requests to populate the document with data. - 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:
In the Figure 2., a user interacting with the documents
resource has the
following flow of information:
- An app calls the
documents.get
method on a web server, with thedocumentId
of the file to find. - 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. - The app parses the JSON so the user can determine what content or format to update.
- The app calls the
documents.batchUpdate
method to atomically perform a set of edit requests to update the document. - 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.
Related topics
- Structure of a Google Docs document
- Requests and responses
- Structural edit rules and behavior
- Best practices for best results