Insert, delete, and move text

The Google Docs API lets you insert or delete text in a document. Moving text involves both operations, preceded by a get of the content.

You can insert or delete text in any of a document's segments (body, header, footer, or footnote).

Insert text

To insert text into a document, use the documents.batchUpdate method and include an InsertTextRequest with the text and location as the payload.

The following code sample shows how you might insert a series of text strings at specified index locations in the body of a document. The example uses three target offsets (25, 50, and 75) and inserts a ten-character string at each location.

Note: Indexes are measured in UTF-16 code units. For more information, see Start and end indexes.

Java

        List<Request> requests = new ArrayList<>();
        requests.add(new Request().setInsertText(new InsertTextRequest()
                .setText(text1)
                .setLocation(new Location().setIndex(25))));

        requests.add(new Request().setInsertText(new InsertTextRequest()
                .setText(text2)
                .setLocation(new Location().setIndex(50))));

        requests.add(new Request().setInsertText(new InsertTextRequest()
                .setText(text3)
                .setLocation(new Location().setIndex(75))));

        BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
        BatchUpdateDocumentResponse response = docsService.documents()
                .batchUpdate(DOCUMENT_ID, body).execute();

PHP

$requests = array();
$requests[] = new Google_Service_Docs_Request(array(
    'insertText' => array(
        'text' => $text1,
        'location' => array(
            'index' => 25,
        ),
    ),
    'insertText' => array(
        'text' => $text2,
        'location' => array(
            'index' => 50,
        ),
    ),
    'insertText' => array(
        'text' => $text3,
        'location' => array(
            'index' => 75,
        ),
    ),
));

$batchUpdateRequest = new Google_Service_Docs_BatchUpdateDocumentRequest(array(
    'requests' => $requests
));

$response = $service->documents->batchUpdate($documentId, $batchUpdateRequest);

Python

    requests = [
         {
            'insertText': {
                'location': {
                    'index': 25,
                },
                'text': text1
            }
        },
                 {
            'insertText': {
                'location': {
                    'index': 50,
                },
                'text': text2
            }
        },
                 {
            'insertText': {
                'location': {
                    'index': 75,
                },
                'text': text3
            }
        },
    ]

    result = service.documents().batchUpdate(
        documentId=DOCUMENT_ID, body={'requests': requests}).execute()

Each insertion increments all the higher-numbered indexes by the size of the inserted text. The example precalculates the result of these index changes so that subsequent insertions happen at the new, corrected offset. Thus to insert at the original target offsets of 25, 50, and 75, the actual insertion indexes are:

• First insertion adds 10 characters at offset 25.
• Second insertion adds 10 characters at offset 50+10=60.
• Third insertion adds 10 characters at offset 75+10+10=95.

Simplify matters by writing backwards. To avoid having to precalculate these offset changes, order your insertions to "write backwards": do the insertion at the highest-numbered index first, working your way towards the beginning with each insertion. This ordering makes sure that each write's offsets are unaffected by the preceding ones.

Delete text

To delete text from a document, first construct a Range that defines the range of text to delete. Then use the documents.batchUpdate method and include a DeleteContentRangeRequest.

Be sure you understand the rules and behavior associated with deleting text.

The following code sample shows how you might delete the text between index 10 and index 24 in the body of a document.

Java

        List<Request> requests = new ArrayList<>();
        requests.add(new Request().setDeleteContentRange(
                new DeleteContentRangeRequest()
                        .setRange(new Range()
                                .setStartIndex(10)
                                .setEndIndex(24))
            ));

        BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
        BatchUpdateDocumentResponse response = docsService.documents()
                .batchUpdate(DOCUMENT_ID, body).execute();

PHP

$requests = array();
$requests[] = new Google_Service_Docs_Request(array(
    'deleteContentRange' => array(
        'range' => array(
            'startIndex' => 10,
            'endIndex' => 24
        ),
    ),
));

$batchUpdateRequest = new Google_Service_Docs_BatchUpdateDocumentRequest(array(
    'requests' => $requests
));

$response = $service->documents->batchUpdate($documentId, $batchUpdateRequest);

Python

    requests = [
        {
            'deleteContentRange': {
                'range': {
                    'startIndex': 10,
                    'endIndex': 24,
                }

            }

        },
    ]
    result = service.documents().batchUpdate(
        documentId=DOCUMENT_ID, body={'requests': requests}).execute()

Simplify matters by writing backwards. As with insertions, deleting text alters the indexes of all the text "below" in the segment. Again, writing backwards can simplify your handling of indexes.

Move text

To move text, you delete it in one location and then insert it elsewhere. Deleting content doesn't give you a copy of it (there's no equivalent concept of a clipboard) so you must extract the contents of the range first so you can use in your insert text request.

Related topics

• Create and manage documents
• Merge text into a document
• Structure of a Google Docs document