Method: spreadsheets.values.append

Appends values to a spreadsheet. The input range is used to search for existing data and find a "table" within that range. Values will be appended to the next row of the table, starting with the first column of the table. See theguide andsample code for specific details of how tables are detected and data is appended.

The caller must specify the spreadsheet ID, range, and avalueInputOption. ThevalueInputOption only controls how the input data will be added to the sheet (column-wise or row-wise), it does not influence what cell the data starts being written to.

HTTP request

POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append

The URL usesgRPC Transcoding syntax.

Path parameters

Parameters
spreadsheetId

string

The ID of the spreadsheet to update.

range

string

TheA1 notation of a range to search for a logical table of data. Values are appended after the last row of the table.

Query parameters

Parameters
valueInputOption

enum (ValueInputOption)

How the input data should be interpreted.

insertDataOption

enum (InsertDataOption)

How the input data should be inserted.

includeValuesInResponse

boolean

Determines if the update response should include the values of the cells that were appended. By default, responses do not include the updated values.

responseValueRenderOption

enum (ValueRenderOption)

Determines how values in the response should be rendered. The default render option isFORMATTED_VALUE.

responseDateTimeRenderOption

enum (DateTimeRenderOption)

Determines how dates, times, and durations in the response should be rendered. This is ignored ifresponseValueRenderOption isFORMATTED_VALUE. The default dateTime render option isSERIAL_NUMBER.

Request body

The request body contains an instance ofValueRange.

Response body

The response when updating a range of values in a spreadsheet.

If successful, the response body contains data with the following structure:

JSON representation
{"spreadsheetId":string,"tableRange":string,"updates":{object (UpdateValuesResponse)}}
Fields
spreadsheetId

string

The spreadsheet the updates were applied to.

tableRange

string

The range (in A1 notation) of the table that values are being appended to (before the values were appended). Empty if no table was found.

updates

object (UpdateValuesResponse)

Information about the updates that were applied.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets

For more information, see theAuthorization guide.

InsertDataOption

Determines how existing data is changed when new data is input.

Enums
OVERWRITEThe new data overwrites existing data in the areas it is written. (Note: adding data to the end of the sheet will still insert new rows or columns so the data can be written.)
INSERT_ROWSRows are inserted for the new data.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-03-21 UTC.