Query Parameters

Query Parameters

All query parameters are appended to the list endpoint:

GET https://sheetsapi.gkit.mreshank.com/api/spreadsheets/{userKey}/{sheetName}?param=value

limit

Type: integer
Default: all rows
Max: 1000

Limits the number of rows returned in a single response. Use together with offset for pagination.

GET /api/spreadsheets/{userKey}/Contacts?limit=25

{
  "data": [ ... ],
  "meta": { "total": 340, "limit": 25, "offset": 0 }
}

offset

Type: integer
Default: 0

Zero-based row offset. Skips the first N data rows before returning results. Combine with limit to paginate through large sheets.

GET /api/spreadsheets/{userKey}/Contacts?limit=25&offset=50

This returns rows 51–75 (zero-indexed rows 50–74).

{
  "data": [ ... ],
  "meta": { "total": 340, "limit": 25, "offset": 50 }
}

search

Type: string, format field:value

Performs a case-insensitive substring match on a specific field. Only rows where the named field contains the value are returned.

GET /api/spreadsheets/{userKey}/Contacts?search=city:London

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

The city:London filter matches both "London" and "East London" because it is a substring match by default. Use search_exact=1 to require an exact match.

search_exact

Type: integer (1 to enable)
Default: disabled

When set to 1, changes the search filter from substring matching to exact match (case-insensitive). Has no effect unless search is also provided.

GET /api/spreadsheets/{userKey}/Contacts?search=city:London&search_exact=1

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

sort

Type: string
Default: sheet order

Sorts the result set by the named field, ascending. Prefix the field name with - (minus) for descending order.

# Most recent entries first
GET /api/spreadsheets/{userKey}/Orders?sort=-date

{
  "data": [
    { "orderId": "1042", "date": "2024-06-20", "amount": "199.00" },
    { "orderId": "1041", "date": "2024-06-18", "amount": "49.99" }
  ],
  "meta": { "total": 1042, "limit": null, "offset": 0 }
}

fields

Type: comma-separated string

Returns only the specified fields in each row object, reducing payload size. Field names must match the header row exactly (case-sensitive).

GET /api/spreadsheets/{userKey}/Contacts?fields=name,email,city

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

Fields not listed in the fields parameter are omitted from the response, even if they exist in the sheet.

format

Type: enum
Default: json
Values: json | csv | tsv | xml | jsonp

Changes the response encoding. When omitted, the API responds with Content-Type: application/json.

# Download as CSV
GET /api/spreadsheets/{userKey}/Contacts?format=csv

See Response Format for the exact structure of each encoding.

callback

Type: string
Only valid with: format=jsonp

Wraps the JSON payload in the named JavaScript function for JSONP usage. The callback name must be a valid JavaScript identifier.

GET /api/spreadsheets/{userKey}/Contacts?format=jsonp&callback=handleData

handleData({"data":[...],"meta":{...}});

Combining Parameters

All parameters can be combined freely. They are applied in this order: filter (search) → sort → offset → limit → field projection → format.

Example — paginated, filtered, sorted, projected CSV:

GET /api/spreadsheets/{userKey}/Orders?search=status:shipped&sort=-date&limit=50&offset=0&fields=orderId,date,amount&format=csv

This returns the 50 most recent shipped orders with only orderId, date, and amount columns, encoded as CSV.

orderId,date,amount
1042,2024-06-20,199.00
1041,2024-06-18,49.99
...