API Reference

Description

Returns all data from a region, paging if necessary.

When paging, the revision parameter must be set and the per_page parameter indicates the maximum number of cells to include in a single response. The server enforces a maximum per_page of 50,000. An unbounded region may only be used to obtain the first page of results. Use the paged_region or next_url from the first page to retrieve subsequent pages. All cells in the requested region will appear exactly once during the paging process, however ordering is not guaranteed.

GET /spreadsheets/{SpreadsheetId}/sheets/{SheetId}/data/{Region}

🚧

Required OAuth Scopes:

data_tables|r

Parameters

ParameterInTypeRequiredDescription
SpreadsheetIdpathstringtrueA unique identifier for a spreadsheet
SheetIdpathstringtrueA unique identifier for a sheet within a spreadsheet
RegionpathstringtrueA1 style representation of a cell or range. A range may be unbounded in any/all directions by leaving off the corresponding column or row.
value_stylequerystringfalseThe style of cell value to return.
revisionqueryinteger(int32)falseThe spreadsheet revision from which to select data. If no revision is provided, the latest revision will be selected.
pagequeryinteger(int32)falseThe page of results to return.
per_pagequeryinteger(int32)falseThe number of items to return per page. Leave blank for no limit, returning all results.

Detailed descriptions

Region: A1 style representation of a cell or range. A range may be unbounded in any/all directions by leaving off the corresponding column or row.

Cell Syntax: [Column][Row]

Range Syntax: [Start Column][Start Row]:[Stop Column][Stop Row]

Examples:

  • The region A1 selects data in the cell A1
  • The region A2:D8 selects all data in the range between A2 and D8 (inclusive)
  • The region A:A selects all data in column A
  • The region 1:3 selects all data in rows 1 through 3
  • The region B3: selects all data below and to the right of B3 (inclusive)
  • The region : selects all data in the sheet

Be sure to URL encode the region to avoid misinterpretation of the :.

value_style: The style of cell value to return.
For example, if a cell's value is =1+1 you can use:

  • raw to get the raw value =1+1
  • calculated to get the calculated value 2

Calculated values will be returned by default.

Enumerated Values

ParameterValue
value_styleraw
value_stylecalculated

Code Samples

curl -X GET https://api.app.wdesk.com/spreadsheets/v1/spreadsheets/{SpreadsheetId}/sheets/{SheetId}/data/{Region}  \ 
-H 'Accept: application/json' \ 
-H 'Authorization: Bearer {access-token}'
http GET https://api.app.wdesk.com/spreadsheets/v1/spreadsheets/{SpreadsheetId}/sheets/{SheetId}/data/{Region}  \ 
Accept:application/json \ 
Authorization:"Bearer {access-token}"
wget --method=GET "https://api.app.wdesk.com/spreadsheets/v1/spreadsheets/{SpreadsheetId}/sheets/{SheetId}/data/{Region}" \
 --output-document -  \ 
 --header 'Accept: application/json' \ 
 --header 'Authorization: Bearer {access-token}'
import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.app.wdesk.com/spreadsheets/v1/spreadsheets/{SpreadsheetId}/sheets/{SheetId}/data/{Region}', headers = headers)

print(r.json())

Returns

200 - OK

Returns a JSON object with the following properties:

  • data - Contains range and values properties. range contains an A1 style representation of the range containing this data. values contains a row-major ordered multidimensional array of cell values.
  • next_url - A fully qualified URL, including next page of results. If there is no next page to query for, this will be empty.
  • page - The one based page index that the result corresponds to. Only included during paging.
  • paged_region - The entire region that the collection of pages represents. Only included during data paging.
  • per_page - The maximum number of items in a page. A page is not guaranteed to have exactly this many items. Only included during paging.
  • revision - The revision number of this spreadsheet.

Example Responses


{
  "data": {
    "range": "A1:B2",
    "values": [
      [
        "Row1-Column1 Data",
        "Row1-Column2 Data"
      ],
      [
        "Row2-Column1 Data",
        "Row2-Column2 Data"
      ]
    ]
  },
  "message": "Operation successful",
  "next_url": "https://api.app.wdesk.com/spreadsheets/v1/spreadsheets/567nd179ed984eb5a52aaaba5f83a230/sheets/k78a604b74564afa76b5ba96755123456/data/A1%3AB20?page=2&per_page=1&revision=3",
  "page": 2,
  "paged_region": "A1:B20",
  "per_page": 1,
  "request_id": "d6a6ce3f-f120-4104-9587-a5a2dc45626c",
  "revision": 3
}