Google Sheets API
  1. spreadsheets
Google Sheets API
  • spreadsheets
    • /v4/spreadsheets
      POST
    • /v4/spreadsheets/{spreadsheetId}
      GET
    • /v4/spreadsheets/{spreadsheetId}/developerMetadata/{metadataId}
      GET
    • /v4/spreadsheets/{spreadsheetId}/developerMetadata:search
      POST
    • /v4/spreadsheets/{spreadsheetId}/sheets/{sheetId}:copyTo
      POST
    • /v4/spreadsheets/{spreadsheetId}/values/{range}
      GET
    • /v4/spreadsheets/{spreadsheetId}/values/{range}
      PUT
    • /v4/spreadsheets/{spreadsheetId}/values/{range}:append
      POST
    • /v4/spreadsheets/{spreadsheetId}/values/{range}:clear
      POST
    • /v4/spreadsheets/{spreadsheetId}/values:batchClear
      POST
    • /v4/spreadsheets/{spreadsheetId}/values:batchClearByDataFilter
      POST
    • /v4/spreadsheets/{spreadsheetId}/values:batchGet
      GET
    • /v4/spreadsheets/{spreadsheetId}/values:batchGetByDataFilter
      POST
    • /v4/spreadsheets/{spreadsheetId}/values:batchUpdate
      POST
    • /v4/spreadsheets/{spreadsheetId}/values:batchUpdateByDataFilter
      POST
    • /v4/spreadsheets/{spreadsheetId}:batchUpdate
      POST
    • /v4/spreadsheets/{spreadsheetId}:getByDataFilter
      POST
  1. spreadsheets

/v4/spreadsheets/{spreadsheetId}:batchUpdate

POST
/v4/spreadsheets/{spreadsheetId}:batchUpdate
spreadsheets
Applies one or more updates to the spreadsheet. Each request is validated before being applied. If any request is not valid then the entire request will fail and nothing will be applied. Some requests have replies to give you some information about how they are applied. The replies will mirror the requests. For example, if you applied 4 updates and the 3rd one had a reply, then the response will have 2 empty replies, the actual reply, and another empty reply, in that order. Due to the collaborative nature of spreadsheets, it is not guaranteed that the spreadsheet will reflect exactly your changes after this completes, however it is guaranteed that the updates in the request will be applied together atomically. Your changes may be altered with respect to collaborator changes. If there are no collaborators, the spreadsheet should reflect your changes.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://sheets.googleapis.com//v4/spreadsheets/:batchUpdate' \
--header 'Content-Type: application/json' \
--data-raw ''
Response Response Example

Request

Path Params
spreadsheetId
string 
required
The spreadsheet to apply the updates to.
Body Params application/json
The request for updating any aspect of a spreadsheet.
includeSpreadsheetInResponse
boolean 
optional
Determines if the update response should include the spreadsheet resource.
requests
array[object (Request) {65}] 
optional
A list of updates to apply to the spreadsheet. Requests will be applied in the order they are specified. If any request is not valid, no requests will be applied.
addBanding
object (AddBandingRequest) 
optional
Adds a new banded range
addChart
object (AddChartRequest) 
optional
Adds a chart.
addConditionalFormatRule
object (AddConditionalFormatRuleRequest) 
optional
Adds a new conditional format rule.
addDataSource
object (AddDataSourceRequest) 
optional
Adds a data source.
addDimensionGroup
object 
optional
addFilterView
object (AddFilterViewRequest) 
optional
Adds a filter view.
addNamedRange
object (AddNamedRangeRequest) 
optional
Adds a named range.
addProtectedRange
object (AddProtectedRangeRequest) 
optional
Adds a protected range.
addSheet
object (AddSheetRequest) 
optional
Adds a sheet.
addSlicer
object (AddSlicerRequest) 
optional
Adds a slicer.
appendCells
object (AppendCellsRequest) 
optional
Appends cells after the last row with data in a sheet.
appendDimension
object (AppendDimensionRequest) 
optional
Appends dimensions to the end of a sheet.
autoFill
object (AutoFillRequest) 
optional
Automatically fills in more data based on existing data.
autoResizeDimensions
object (AutoResizeDimensionsRequest) 
optional
Automatically resizes one or more dimensions based on the contents of the cells in that dimension.
clearBasicFilter
object (ClearBasicFilterRequest) 
optional
Clears the basic filter on a sheet.
copyPaste
object (CopyPasteRequest) 
optional
Copies data from one area and pastes it to another.
createDeveloperMetadata
object (CreateDeveloperMetadataRequest) 
optional
Creates new developer metadata
cutPaste
object (CutPasteRequest) 
optional
Cuts data from one area and pastes it to another.
deleteBanding
object (DeleteBandingRequest) 
optional
Removes a banded range
deleteConditionalFormatRule
object (DeleteConditionalFormatRuleRequest) 
optional
Deletes an existing conditional format rule.
deleteDataSource
object (DeleteDataSourceRequest) 
optional
Deletes a data source.
deleteDeveloperMetadata
object (DeleteDeveloperMetadataRequest) 
optional
Deletes developer metadata
deleteDimension
object (DeleteDimensionRequest) 
optional
Deletes rows or columns in a sheet.
deleteDimensionGroup
object (DeleteDimensionGroupRequest) 
optional
Deletes a group over the specified range.
deleteDuplicates
object 
optional
deleteEmbeddedObject
object (DeleteEmbeddedObjectRequest) 
optional
Deletes an embedded object (e.g, chart, image) in a sheet.
deleteFilterView
object (DeleteFilterViewRequest) 
optional
Deletes a filter view from a sheet.
deleteNamedRange
object (DeleteNamedRangeRequest) 
optional
Deletes a named range.
deleteProtectedRange
object (DeleteProtectedRangeRequest) 
optional
Deletes a protected range.
deleteRange
object (DeleteRangeRequest) 
optional
Deletes a range of cells from a sheet, shifting the remaining cells.
deleteSheet
object (DeleteSheetRequest) 
optional
Deletes a sheet.
duplicateFilterView
object (DuplicateFilterViewRequest) 
optional
Duplicates a filter view.
duplicateSheet
object (DuplicateSheetRequest) 
optional
Duplicates a sheet.
findReplace
object (FindReplaceRequest) 
optional
Finds and replaces occurrences of some text with other text.
insertDimension
object (InsertDimensionRequest) 
optional
Inserts new rows or columns in a sheet.
insertRange
object (InsertRangeRequest) 
optional
Inserts new cells in a sheet, shifting the existing cells.
mergeCells
object (MergeCellsRequest) 
optional
Merges cells together.
moveDimension
object (MoveDimensionRequest) 
optional
Moves rows or columns to another location in a sheet.
pasteData
object (PasteDataRequest) 
optional
Pastes data (HTML or delimited) into a sheet.
randomizeRange
object (RandomizeRangeRequest) 
optional
Randomizes the order of the rows in a range.
refreshDataSource
object (RefreshDataSourceRequest) 
optional
Refreshs one or multiple data sources and associated dbobjects.
repeatCell
object 
optional
setBasicFilter
object (SetBasicFilterRequest) 
optional
Sets the basic filter on a sheet.
setDataValidation
object (SetDataValidationRequest) 
optional
Sets data validation for one or more cells.
sortRange
object (SortRangeRequest) 
optional
Sorts data in a range.
textToColumns
object (TextToColumnsRequest) 
optional
Converts a column of text into many columns of text.
trimWhitespace
object (TrimWhitespaceRequest) 
optional
Trims cells of whitespace (such as spaces, tabs, or new lines).
unmergeCells
object (UnmergeCellsRequest) 
optional
Unmerges merged cells.
updateBanding
object (UpdateBandingRequest) 
optional
Updates a banded range
updateBorders
object (UpdateBordersRequest) 
optional
Updates the borders in a range of cells.
updateCells
object (UpdateCellsRequest) 
optional
Updates many cells at once.
updateChartSpec
object (UpdateChartSpecRequest) 
optional
Updates a chart's specifications.
updateConditionalFormatRule
object (UpdateConditionalFormatRuleRequest) 
optional
Updates an existing conditional format rule.
updateDataSource
object (UpdateDataSourceRequest) 
optional
Updates a data source.
updateDeveloperMetadata
object (UpdateDeveloperMetadataRequest) 
optional
Updates an existing developer metadata entry
updateDimensionGroup
object (UpdateDimensionGroupRequest) 
optional
Updates the state of the specified group.
updateDimensionProperties
object (UpdateDimensionPropertiesRequest) 
optional
Updates dimensions' properties.
updateEmbeddedObjectBorder
object (UpdateEmbeddedObjectBorderRequest) 
optional
Updates an embedded object's border.
updateEmbeddedObjectPosition
object (UpdateEmbeddedObjectPositionRequest) 
optional
Updates an embedded object's (e.g. chart, image) position.
updateFilterView
object (UpdateFilterViewRequest) 
optional
Updates the properties of a filter view.
updateNamedRange
object (UpdateNamedRangeRequest) 
optional
Updates a named range.
updateProtectedRange
object (UpdateProtectedRangeRequest) 
optional
Updates a protected range.
updateSheetProperties
object (UpdateSheetPropertiesRequest) 
optional
Updates a sheet's properties.
updateSlicerSpec
object (UpdateSlicerSpecRequest) 
optional
Updates a slicer's specifications.
updateSpreadsheetProperties
object (UpdateSpreadsheetPropertiesRequest) 
optional
Updates the spreadsheet's properties.
responseIncludeGridData
boolean 
optional
True if grid data should be returned. Meaningful only if include_spreadsheet_in_response is 'true'. This parameter is ignored if a field mask was set in the request.
responseRanges
array[string]
optional
Limits the ranges included in the response spreadsheet. Meaningful only if include_spreadsheet_in_response is 'true'.
Examples

Responses

🟢200Successful response
application/json
Body
The reply for batch updating a spreadsheet.
replies
array[object (Response) {23}] 
optional
The reply of the updates. This maps 1:1 with the updates, although replies to some requests may be empty.
addBanding
object (AddBandingResponse) 
optional
A reply from adding a banded range.
addChart
object (AddChartResponse) 
optional
A reply from adding a chart.
addDataSource
object (AddDataSourceResponse) 
optional
A reply from adding a data source.
addDimensionGroup
object (AddDimensionGroupResponse) 
optional
A reply from adding a dimension group.
addFilterView
object (AddFilterViewResponse) 
optional
A reply from adding a filter view.
addNamedRange
object (AddNamedRangeResponse) 
optional
A reply from adding a named range.
addProtectedRange
object (AddProtectedRangeResponse) 
optional
A reply from adding a protected range.
addSheet
object (AddSheetResponse) 
optional
A reply from adding a sheet.
addSlicer
object (AddSlicerResponse) 
optional
A reply from adding a slicer.
createDeveloperMetadata
object (CreateDeveloperMetadataResponse) 
optional
A reply from creating a developer metadata entry.
deleteConditionalFormatRule
object (DeleteConditionalFormatRuleResponse) 
optional
A reply from deleting a conditional format rule.
deleteDeveloperMetadata
object (DeleteDeveloperMetadataResponse) 
optional
A reply from deleting a developer metadata entry.
deleteDimensionGroup
object (DeleteDimensionGroupResponse) 
optional
A reply from deleting a dimension group.
deleteDuplicates
object (DeleteDuplicatesResponse) 
optional
A reply from removing rows containing duplicate values.
duplicateFilterView
object (DuplicateFilterViewResponse) 
optional
A reply from duplicating a filter view.
duplicateSheet
object (DuplicateSheetResponse) 
optional
A reply from duplicating a sheet.
findReplace
object (FindReplaceResponse) 
optional
A reply from doing a find/replace.
refreshDataSource
object (RefreshDataSourceResponse) 
optional
A reply from refreshing data source objects.
trimWhitespace
object (TrimWhitespaceResponse) 
optional
A reply from trimming whitespace.
updateConditionalFormatRule
object (UpdateConditionalFormatRuleResponse) 
optional
A reply from updating a conditional format rule.
updateDataSource
object (UpdateDataSourceResponse) 
optional
A reply from updating a data source.
updateDeveloperMetadata
object (UpdateDeveloperMetadataResponse) 
optional
A reply from updating a developer metadata entry.
updateEmbeddedObjectPosition
object (UpdateEmbeddedObjectPositionResponse) 
optional
A reply from updating an embedded object's position.
spreadsheetId
string 
optional
The spreadsheet the updates were applied to.
updatedSpreadsheet
object (Spreadsheet) 
optional
The spreadsheet after updates were applied. This is only set if BatchUpdateSpreadsheetRequest.include_spreadsheet_in_response is true.
dataSourceSchedules
array[object (DataSourceRefreshSchedule) {6}] 
read-onlyoptional
Output only. A list of data source refresh schedules.
dataSources
array[object (DataSource) {4}] 
optional
A list of external data sources connected with the spreadsheet.
developerMetadata
array [object] 
optional
The developer metadata associated with a spreadsheet.
namedRanges
array[object (NamedRange) {3}] 
optional
The named ranges defined in a spreadsheet.
properties
object (SpreadsheetProperties) 
optional
Overall properties of a spreadsheet.
sheets
array[object (Sheet) {13}] 
optional
The sheets that are part of a spreadsheet.
spreadsheetId
string 
optional
The ID of the spreadsheet. This field is read-only.
spreadsheetUrl
string 
optional
The url of the spreadsheet. This field is read-only.
Previous
/v4/spreadsheets/{spreadsheetId}/values:batchUpdateByDataFilter
Next
/v4/spreadsheets/{spreadsheetId}:getByDataFilter
Built with