Response Format

Response Format

SheetsAPI maps your spreadsheet data directly to structured API responses. This page covers every response shape the API can return.

JSON (default)

The default response for a list request is a JSON object with two top-level keys:

{
  "data": [
    { "name": "Alice", "email": "alice@example.com", "city": "London" },
    { "name": "Bob",   "email": "bob@example.com",   "city": "Manchester" }
  ],
  "meta": {
    "total": 340,
    "limit": 25,
    "offset": 0
  }
}

data

An array of row objects. Each object represents one spreadsheet row. Keys come from the first row of the sheet tab (the header row), and values come from the corresponding cells.

meta

How Rows Map to Objects

The first row of each sheet tab defines the field names (keys) for every row object. Subsequent rows become the data.

Sheet tab "Contacts":

API response:

{
  "data": [
    { "name": "Alice", "email": "alice@example.com", "city": "London" },
    { "name": "Bob",   "email": "bob@example.com",   "city": "Manchester" }
  ],
  "meta": { "total": 2, "limit": null, "offset": 0 }
}

Column headers with spaces or special characters are preserved as-is in the key name. It is recommended to use lowercase alphanumeric headers for the cleanest API surface.

Null and Empty Cells

Cells that are empty or contain only whitespace are omitted from the row object entirely (they do not appear as null). If you need to detect missing values in your application, treat any absent key as equivalent to an empty cell.

{ "name": "Carol", "city": "Leeds" }

In this example, email was blank in the sheet and is not present in the object.

Single Row Endpoint

Fetching a specific row by its 1-based row number (GET /{userKey}/{sheetName}/{row}) returns the row object directly — not wrapped in a data array.

GET /api/spreadsheets/{userKey}/Contacts/3

{ "name": "Bob", "email": "bob@example.com", "city": "Manchester" }

There is no meta object in single-row responses.

Error Responses

All errors return a JSON object with a single error key and an appropriate HTTP status code.

{ "error": "Sheet not found" }

CSV Format (format=csv)

When ?format=csv is set, the response is plain text/csv. The first line is the header row derived from the sheet headers; subsequent lines are data rows. Fields containing commas or quotes are properly escaped per RFC 4180.

name,email,city
Alice,alice@example.com,London
Bob,bob@example.com,Manchester

There is no meta object in CSV responses.

TSV Format (format=tsv)

Identical to CSV but uses tab characters as the delimiter. Content-Type is text/tab-separated-values.

name	email	city
Alice	alice@example.com	London
Bob	bob@example.com	Manchester

XML Format (format=xml)

When ?format=xml is set, each row is wrapped in a <row> element, and all rows are contained in a <rows> root element. Each field becomes a child element named after the column header.

<?xml version="1.0" encoding="UTF-8"?>
<rows>
  <row>
    <name>Alice</name>
    <email>alice@example.com</email>
    <city>London</city>
  </row>
  <row>
    <name>Bob</name>
    <email>bob@example.com</email>
    <city>Manchester</city>
  </row>
</rows>

JSONP Format (format=jsonp)

When ?format=jsonp&callback=myFn is set, the full JSON payload (same shape as the default JSON response) is wrapped in the named callback function and returned as application/javascript.

myFn({"data":[{"name":"Alice","email":"alice@example.com","city":"London"}],"meta":{"total":1,"limit":null,"offset":0}});

The callback parameter is required when using format=jsonp. The callback name must be a valid JavaScript identifier.