# Google Sheets API . spreadsheets . values

## Instance Methods

Appends values to a spreadsheet. The input range is used to search for

Clears one or more ranges of values from a spreadsheet.

Returns one or more ranges of values from a spreadsheet.

Sets values in one or more ranges of a spreadsheet.

Clears values from a spreadsheet.

Returns a range of values from a spreadsheet.

Sets values in a range of a spreadsheet.

### Method Details

`append(spreadsheetId, range=None, body, valueInputOption=None, x__xgafv=None, responseValueRenderOption=None, insertDataOption=None, includeValuesInResponse=None, responseDateTimeRenderOption=None)`

    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 the
    [guide](/sheets/guides/values#appending_values)
    and
    [sample code](/sheets/samples/writing#append_values)
    for specific details of how tables are detected and data is appended.

    The caller must specify the spreadsheet ID, range, and
    a valueInputOption.  The `valueInputOption` 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.

    Args:
      spreadsheetId: string, The ID of the spreadsheet to update. (required)
      range: string, The A1 notation of a range to search for a logical table of data.
    Values will be appended after the last row of the table. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # Data within a range of the spreadsheet.
      "range": "A String", # The range the values cover, in A1 notation.
          # For output, this range indicates the entire requested range,
          # even though the values will exclude trailing rows and columns.
          # When appending values, this field represents the range to search for a
          # table, after which values will be appended.
      "values": [ # The data that was read or to be written.  This is an array of arrays,
          # the outer array representing all the data and each inner array
          # representing a major dimension. Each item in the inner array
          # corresponds with one cell.
          #
          # For output, empty trailing rows and columns will not be included.
          #
          # For input, supported value types are: bool, string, and double.
          # Null values will be skipped.
          # To set a cell to an empty value, set the string value to an empty string.
        [
          "",
        ],
      ],
      "majorDimension": "A String", # The major dimension of the values.
          #
          # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
          # then requesting `range=A1:B2,majorDimension=ROWS` will return
          # `[[1,2],[3,4]]`,
          # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
          # `[[1,3],[2,4]]`.
          #
          # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
          # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
          # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
          #
          # When writing, if this field is not set, it defaults to ROWS.
    }

      valueInputOption: string, How the input data should be interpreted.
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format
      responseValueRenderOption: string, Determines how values in the response should be rendered.
    The default render option is ValueRenderOption.FORMATTED_VALUE.
      insertDataOption: string, 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.
      responseDateTimeRenderOption: string, Determines how dates, times, and durations in the response should be
    rendered. This is ignored if response_value_render_option is
    FORMATTED_VALUE.
    The default dateTime render option is [DateTimeRenderOption.SERIAL_NUMBER].

    Returns:
      An object of the form:

        { # The response when updating a range of values in a spreadsheet.
        "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
        "tableRange": "A 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": { # The response when updating a range of values in a spreadsheet. # Information about the updates that were applied.
          "updatedColumns": 42, # The number of columns where at least one cell in the column was updated.
          "updatedRange": "A String", # The range (in A1 notation) that updates were applied to.
          "updatedRows": 42, # The number of rows where at least one cell in the row was updated.
          "updatedData": { # Data within a range of the spreadsheet. # The values of the cells after updates were applied.
              # This is only included if the request's `includeValuesInResponse` field
              # was `true`.
            "range": "A String", # The range the values cover, in A1 notation.
                # For output, this range indicates the entire requested range,
                # even though the values will exclude trailing rows and columns.
                # When appending values, this field represents the range to search for a
                # table, after which values will be appended.
            "values": [ # The data that was read or to be written.  This is an array of arrays,
                # the outer array representing all the data and each inner array
                # representing a major dimension. Each item in the inner array
                # corresponds with one cell.
                #
                # For output, empty trailing rows and columns will not be included.
                #
                # For input, supported value types are: bool, string, and double.
                # Null values will be skipped.
                # To set a cell to an empty value, set the string value to an empty string.
              [
                "",
              ],
            ],
            "majorDimension": "A String", # The major dimension of the values.
                #
                # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
                # then requesting `range=A1:B2,majorDimension=ROWS` will return
                # `[[1,2],[3,4]]`,
                # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
                # `[[1,3],[2,4]]`.
                #
                # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
                # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
                # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
                #
                # When writing, if this field is not set, it defaults to ROWS.
          },
          "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
          "updatedCells": 42, # The number of cells updated.
        },
      }

`batchClear(spreadsheetId, body, x__xgafv=None)`

    Clears one or more ranges of values from a spreadsheet.
    The caller must specify the spreadsheet ID and one or more ranges.
    Only values are cleared -- all other properties of the cell (such as
    formatting, data validation, etc..) are kept.

    Args:
      spreadsheetId: string, The ID of the spreadsheet to update. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # The request for clearing more than one range of values in a spreadsheet.
        "ranges": [ # The ranges to clear, in A1 notation.
          "A String",
        ],
      }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # The response when updating a range of values in a spreadsheet.
        "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
        "clearedRanges": [ # The ranges that were cleared, in A1 notation.
            # (If the requests were for an unbounded range or a ranger larger
            #  than the bounds of the sheet, this will be the actual ranges
            #  that were cleared, bounded to the sheet's limits.)
          "A String",
        ],
      }

`batchGet(spreadsheetId, valueRenderOption=None, majorDimension=None, ranges=None, dateTimeRenderOption=None, x__xgafv=None)`

    Returns one or more ranges of values from a spreadsheet.
    The caller must specify the spreadsheet ID and one or more ranges.

    Args:
      spreadsheetId: string, The ID of the spreadsheet to retrieve data from. (required)
      valueRenderOption: string, How values should be represented in the output.
    The default render option is ValueRenderOption.FORMATTED_VALUE.
      majorDimension: string, The major dimension that results should use.

    For example, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
    then requesting `range=A1:B2,majorDimension=ROWS` will return
    `[[1,2],[3,4]]`,
    whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
    `[[1,3],[2,4]]`.
      ranges: string, The A1 notation of the values to retrieve. (repeated)
      dateTimeRenderOption: string, How dates, times, and durations should be represented in the output.
    This is ignored if value_render_option is
    FORMATTED_VALUE.
    The default dateTime render option is [DateTimeRenderOption.SERIAL_NUMBER].
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # The response when retrieving more than one range of values in a spreadsheet.
        "spreadsheetId": "A String", # The ID of the spreadsheet the data was retrieved from.
        "valueRanges": [ # The requested values. The order of the ValueRanges is the same as the
            # order of the requested ranges.
          { # Data within a range of the spreadsheet.
            "range": "A String", # The range the values cover, in A1 notation.
                # For output, this range indicates the entire requested range,
                # even though the values will exclude trailing rows and columns.
                # When appending values, this field represents the range to search for a
                # table, after which values will be appended.
            "values": [ # The data that was read or to be written.  This is an array of arrays,
                # the outer array representing all the data and each inner array
                # representing a major dimension. Each item in the inner array
                # corresponds with one cell.
                #
                # For output, empty trailing rows and columns will not be included.
                #
                # For input, supported value types are: bool, string, and double.
                # Null values will be skipped.
                # To set a cell to an empty value, set the string value to an empty string.
              [
                "",
              ],
            ],
            "majorDimension": "A String", # The major dimension of the values.
                #
                # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
                # then requesting `range=A1:B2,majorDimension=ROWS` will return
                # `[[1,2],[3,4]]`,
                # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
                # `[[1,3],[2,4]]`.
                #
                # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
                # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
                # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
                #
                # When writing, if this field is not set, it defaults to ROWS.
          },
        ],
      }

`batchUpdate(spreadsheetId, body, x__xgafv=None)`

    Sets values in one or more ranges of a spreadsheet.
    The caller must specify the spreadsheet ID,
    a valueInputOption, and one or more
    ValueRanges.

    Args:
      spreadsheetId: string, The ID of the spreadsheet to update. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # The request for updating more than one range of values in a spreadsheet.
        "includeValuesInResponse": True or False, # Determines if the update response should include the values
            # of the cells that were updated. By default, responses
            # do not include the updated values. The `updatedData` field within
            # each of the BatchUpdateValuesResponse.responses will contain
            # the updated values. If the range to write was larger than than the range
            # actually written, the response will include all values in the requested
            # range (excluding trailing empty rows and columns).
        "data": [ # The new values to apply to the spreadsheet.
          { # Data within a range of the spreadsheet.
            "range": "A String", # The range the values cover, in A1 notation.
                # For output, this range indicates the entire requested range,
                # even though the values will exclude trailing rows and columns.
                # When appending values, this field represents the range to search for a
                # table, after which values will be appended.
            "values": [ # The data that was read or to be written.  This is an array of arrays,
                # the outer array representing all the data and each inner array
                # representing a major dimension. Each item in the inner array
                # corresponds with one cell.
                #
                # For output, empty trailing rows and columns will not be included.
                #
                # For input, supported value types are: bool, string, and double.
                # Null values will be skipped.
                # To set a cell to an empty value, set the string value to an empty string.
              [
                "",
              ],
            ],
            "majorDimension": "A String", # The major dimension of the values.
                #
                # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
                # then requesting `range=A1:B2,majorDimension=ROWS` will return
                # `[[1,2],[3,4]]`,
                # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
                # `[[1,3],[2,4]]`.
                #
                # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
                # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
                # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
                #
                # When writing, if this field is not set, it defaults to ROWS.
          },
        ],
        "responseValueRenderOption": "A String", # Determines how values in the response should be rendered.
            # The default render option is ValueRenderOption.FORMATTED_VALUE.
        "valueInputOption": "A String", # How the input data should be interpreted.
        "responseDateTimeRenderOption": "A String", # Determines how dates, times, and durations in the response should be
            # rendered. This is ignored if response_value_render_option is
            # FORMATTED_VALUE.
            # The default dateTime render option is [DateTimeRenderOption.SERIAL_NUMBER].
      }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # The response when updating a range of values in a spreadsheet.
        "responses": [ # One UpdateValuesResponse per requested range, in the same order as
            # the requests appeared.
          { # The response when updating a range of values in a spreadsheet.
            "updatedColumns": 42, # The number of columns where at least one cell in the column was updated.
            "updatedRange": "A String", # The range (in A1 notation) that updates were applied to.
            "updatedRows": 42, # The number of rows where at least one cell in the row was updated.
            "updatedData": { # Data within a range of the spreadsheet. # The values of the cells after updates were applied.
                # This is only included if the request's `includeValuesInResponse` field
                # was `true`.
              "range": "A String", # The range the values cover, in A1 notation.
                  # For output, this range indicates the entire requested range,
                  # even though the values will exclude trailing rows and columns.
                  # When appending values, this field represents the range to search for a
                  # table, after which values will be appended.
              "values": [ # The data that was read or to be written.  This is an array of arrays,
                  # the outer array representing all the data and each inner array
                  # representing a major dimension. Each item in the inner array
                  # corresponds with one cell.
                  #
                  # For output, empty trailing rows and columns will not be included.
                  #
                  # For input, supported value types are: bool, string, and double.
                  # Null values will be skipped.
                  # To set a cell to an empty value, set the string value to an empty string.
                [
                  "",
                ],
              ],
              "majorDimension": "A String", # The major dimension of the values.
                  #
                  # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
                  # then requesting `range=A1:B2,majorDimension=ROWS` will return
                  # `[[1,2],[3,4]]`,
                  # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
                  # `[[1,3],[2,4]]`.
                  #
                  # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
                  # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
                  # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
                  #
                  # When writing, if this field is not set, it defaults to ROWS.
            },
            "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
            "updatedCells": 42, # The number of cells updated.
          },
        ],
        "totalUpdatedCells": 42, # The total number of cells updated.
        "totalUpdatedColumns": 42, # The total number of columns where at least one cell in the column was
            # updated.
        "totalUpdatedRows": 42, # The total number of rows where at least one cell in the row was updated.
        "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
        "totalUpdatedSheets": 42, # The total number of sheets where at least one cell in the sheet was
            # updated.
      }

`clear(spreadsheetId, range, body, x__xgafv=None)`

    Clears values from a spreadsheet.
    The caller must specify the spreadsheet ID and range.
    Only values are cleared -- all other properties of the cell (such as
    formatting, data validation, etc..) are kept.

    Args:
      spreadsheetId: string, The ID of the spreadsheet to update. (required)
      range: string, The A1 notation of the values to clear. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # The request for clearing a range of values in a spreadsheet.
      }

      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # The response when clearing a range of values in a spreadsheet.
        "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
        "clearedRange": "A String", # The range (in A1 notation) that was cleared.
            # (If the request was for an unbounded range or a ranger larger
            #  than the bounds of the sheet, this will be the actual range
            #  that was cleared, bounded to the sheet's limits.)
      }

`get(spreadsheetId, range, valueRenderOption=None, majorDimension=None, dateTimeRenderOption=None, x__xgafv=None)`

    Returns a range of values from a spreadsheet.
    The caller must specify the spreadsheet ID and a range.

    Args:
      spreadsheetId: string, The ID of the spreadsheet to retrieve data from. (required)
      range: string, The A1 notation of the values to retrieve. (required)
      valueRenderOption: string, How values should be represented in the output.
    The default render option is ValueRenderOption.FORMATTED_VALUE.
      majorDimension: string, The major dimension that results should use.

    For example, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
    then requesting `range=A1:B2,majorDimension=ROWS` will return
    `[[1,2],[3,4]]`,
    whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
    `[[1,3],[2,4]]`.
      dateTimeRenderOption: string, How dates, times, and durations should be represented in the output.
    This is ignored if value_render_option is
    FORMATTED_VALUE.
    The default dateTime render option is [DateTimeRenderOption.SERIAL_NUMBER].
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # Data within a range of the spreadsheet.
        "range": "A String", # The range the values cover, in A1 notation.
            # For output, this range indicates the entire requested range,
            # even though the values will exclude trailing rows and columns.
            # When appending values, this field represents the range to search for a
            # table, after which values will be appended.
        "values": [ # The data that was read or to be written.  This is an array of arrays,
            # the outer array representing all the data and each inner array
            # representing a major dimension. Each item in the inner array
            # corresponds with one cell.
            #
            # For output, empty trailing rows and columns will not be included.
            #
            # For input, supported value types are: bool, string, and double.
            # Null values will be skipped.
            # To set a cell to an empty value, set the string value to an empty string.
          [
            "",
          ],
        ],
        "majorDimension": "A String", # The major dimension of the values.
            #
            # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
            # then requesting `range=A1:B2,majorDimension=ROWS` will return
            # `[[1,2],[3,4]]`,
            # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
            # `[[1,3],[2,4]]`.
            #
            # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
            # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
            # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
            #
            # When writing, if this field is not set, it defaults to ROWS.
      }

`update(spreadsheetId, range, body, valueInputOption=None, x__xgafv=None, responseValueRenderOption=None, includeValuesInResponse=None, responseDateTimeRenderOption=None)`

    Sets values in a range of a spreadsheet.
    The caller must specify the spreadsheet ID, range, and
    a valueInputOption.

    Args:
      spreadsheetId: string, The ID of the spreadsheet to update. (required)
      range: string, The A1 notation of the values to update. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # Data within a range of the spreadsheet.
      "range": "A String", # The range the values cover, in A1 notation.
          # For output, this range indicates the entire requested range,
          # even though the values will exclude trailing rows and columns.
          # When appending values, this field represents the range to search for a
          # table, after which values will be appended.
      "values": [ # The data that was read or to be written.  This is an array of arrays,
          # the outer array representing all the data and each inner array
          # representing a major dimension. Each item in the inner array
          # corresponds with one cell.
          #
          # For output, empty trailing rows and columns will not be included.
          #
          # For input, supported value types are: bool, string, and double.
          # Null values will be skipped.
          # To set a cell to an empty value, set the string value to an empty string.
        [
          "",
        ],
      ],
      "majorDimension": "A String", # The major dimension of the values.
          #
          # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
          # then requesting `range=A1:B2,majorDimension=ROWS` will return
          # `[[1,2],[3,4]]`,
          # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
          # `[[1,3],[2,4]]`.
          #
          # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
          # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
          # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
          #
          # When writing, if this field is not set, it defaults to ROWS.
    }

      valueInputOption: string, How the input data should be interpreted.
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format
      responseValueRenderOption: string, Determines how values in the response should be rendered.
    The default render option is ValueRenderOption.FORMATTED_VALUE.
      includeValuesInResponse: boolean, Determines if the update response should include the values
    of the cells that were updated. By default, responses
    do not include the updated values.
    If the range to write was larger than than the range actually written,
    the response will include all values in the requested range (excluding
    trailing empty rows and columns).
      responseDateTimeRenderOption: string, Determines how dates, times, and durations in the response should be
    rendered. This is ignored if response_value_render_option is
    FORMATTED_VALUE.
    The default dateTime render option is [DateTimeRenderOption.SERIAL_NUMBER].

    Returns:
      An object of the form:

        { # The response when updating a range of values in a spreadsheet.
        "updatedColumns": 42, # The number of columns where at least one cell in the column was updated.
        "updatedRange": "A String", # The range (in A1 notation) that updates were applied to.
        "updatedRows": 42, # The number of rows where at least one cell in the row was updated.
        "updatedData": { # Data within a range of the spreadsheet. # The values of the cells after updates were applied.
            # This is only included if the request's `includeValuesInResponse` field
            # was `true`.
          "range": "A String", # The range the values cover, in A1 notation.
              # For output, this range indicates the entire requested range,
              # even though the values will exclude trailing rows and columns.
              # When appending values, this field represents the range to search for a
              # table, after which values will be appended.
          "values": [ # The data that was read or to be written.  This is an array of arrays,
              # the outer array representing all the data and each inner array
              # representing a major dimension. Each item in the inner array
              # corresponds with one cell.
              #
              # For output, empty trailing rows and columns will not be included.
              #
              # For input, supported value types are: bool, string, and double.
              # Null values will be skipped.
              # To set a cell to an empty value, set the string value to an empty string.
            [
              "",
            ],
          ],
          "majorDimension": "A String", # The major dimension of the values.
              #
              # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
              # then requesting `range=A1:B2,majorDimension=ROWS` will return
              # `[[1,2],[3,4]]`,
              # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
              # `[[1,3],[2,4]]`.
              #
              # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
              # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
              # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
              #
              # When writing, if this field is not set, it defaults to ROWS.
        },
        "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
        "updatedCells": 42, # The number of cells updated.
      }