Spreadsheets are grids — rows and columns. When you ask Sheets for a range, the response shape mirrors that grid. What do you think comes back?
A list of lists? Each inner list is one row of cell values?
Exactly. GOOGLESHEETS_BATCH_GET takes a spreadsheet_id and a ranges list and returns {"values": [[row1], [row2], ...]}. Rows are lists, cells are strings:
result = toolset.execute_action(Action.GOOGLESHEETS_BATCH_GET, {
"spreadsheet_id": "abc123",
"ranges": ["Sheet1!A1:B10"],
})
rows = result.get("values", [])The range looks like A1 notation — Sheet1!A1:B10. Is that the same syntax I'd type into Google Sheets?
Identical. The tab name, an exclamation mark, the cell range — same as the UI. That is on purpose: whatever you can select in the browser, you can pass to the API. Wrap it up:
def read_first_sheet(spreadsheet_id: str, range_name: str) -> list:
result = toolset.execute_action(Action.GOOGLESHEETS_BATCH_GET, {
"spreadsheet_id": spreadsheet_id,
"ranges": [range_name],
})
return result.get("values", [])What if the range is totally empty — all blank cells? Does the API return empty rows or drop them?
Sheets trims trailing empties. An empty range usually comes back as {} with no "values" key at all. That is why the .get("values", []) default lands on an empty list — your function returns [] on empty ranges instead of crashing.
And once I have the rows as a list of lists, every Python tool I know works — iterate, slice, filter, summarize?
That is the whole value of getting clean data out of the API: after that, it is ordinary Python. Pandas, list comprehensions, whatever you reach for — all of it applies directly.
TL;DR: Sheets returns grid data as a list of row lists under the values key; empty ranges drop the key entirely.
Action.GOOGLESHEETS_BATCH_GETspreadsheet_id plus ranges (list of A1 strings){"values": [["A1", "B1"], ["A2", "B2"]]}.get("values", []) defaults to []| String | Meaning |
|---|---|
Sheet1!A1:B10 | cols A–B, rows 1–10 on Sheet1 |
A:A | entire column A |
Spreadsheets are grids — rows and columns. When you ask Sheets for a range, the response shape mirrors that grid. What do you think comes back?
A list of lists? Each inner list is one row of cell values?
Exactly. GOOGLESHEETS_BATCH_GET takes a spreadsheet_id and a ranges list and returns {"values": [[row1], [row2], ...]}. Rows are lists, cells are strings:
result = toolset.execute_action(Action.GOOGLESHEETS_BATCH_GET, {
"spreadsheet_id": "abc123",
"ranges": ["Sheet1!A1:B10"],
})
rows = result.get("values", [])The range looks like A1 notation — Sheet1!A1:B10. Is that the same syntax I'd type into Google Sheets?
Identical. The tab name, an exclamation mark, the cell range — same as the UI. That is on purpose: whatever you can select in the browser, you can pass to the API. Wrap it up:
def read_first_sheet(spreadsheet_id: str, range_name: str) -> list:
result = toolset.execute_action(Action.GOOGLESHEETS_BATCH_GET, {
"spreadsheet_id": spreadsheet_id,
"ranges": [range_name],
})
return result.get("values", [])What if the range is totally empty — all blank cells? Does the API return empty rows or drop them?
Sheets trims trailing empties. An empty range usually comes back as {} with no "values" key at all. That is why the .get("values", []) default lands on an empty list — your function returns [] on empty ranges instead of crashing.
And once I have the rows as a list of lists, every Python tool I know works — iterate, slice, filter, summarize?
That is the whole value of getting clean data out of the API: after that, it is ordinary Python. Pandas, list comprehensions, whatever you reach for — all of it applies directly.
TL;DR: Sheets returns grid data as a list of row lists under the values key; empty ranges drop the key entirely.
Action.GOOGLESHEETS_BATCH_GETspreadsheet_id plus ranges (list of A1 strings){"values": [["A1", "B1"], ["A2", "B2"]]}.get("values", []) defaults to []| String | Meaning |
|---|---|
Sheet1!A1:B10 | cols A–B, rows 1–10 on Sheet1 |
A:A | entire column A |
Create a free account to get started. Paid plans unlock all tracks.