SheetDB API Documentation

Introduction

Every spreadsheet document you want to access has to be setup in SheetDB panel as an API. Once API is made you'll get an unique http address. You can send RESTful request to it to read, create, update or delete rows. The rest of this docummentation will explain how each request works and what you will get as a response.

Installation

There is no need to any setup. As long as you can make http requests and use JSON format you're good to go!

You can also use one of our Libraries.
Library for JavaScript on GitHub
Library for PHP on GitHub

Example spreadsheet

At any time you can play with our test API here: https://sheetdb.io/api/v1/58f61be4dda40

You can also go to Google Sheets and play with it: https://docs.google.com/spreadsheets/d/1mrsgBk4IAdSs8Ask5H1z3bWYDlPTKplDIU_FzyktrGk/edit. The spreadsheet resets every hour.

First row of your spreadsheet should contain the column names. Each next row will be treated as a record (according to naming from first row).

Our Example spreadsheet looks like this:

id name age comment
1 Tom 41
2 Alex 24
3 John 51
61 Steve 22 special
422 James 19

HTTP Status Codes

Every response is in JSON format. Of course there is a status code in every response. Here is a list of available response codes:

Status Code
200 OK The request has succeeded for GET, PUT, PATCH and DELETE requests.
201 Created The request has succeeded for POST requests.
400 Bad Request The request could not be understood by the API.
401 Unauthorized Pretty self-explanatory. Error with authorization either with Google Account or SheetDB.
402 Payment Required Payment is required to process request.
403 Forbidden Action is forbidden.
404 Not Found The server has not found anything matching the Request.
429 Too Many Requests Exhausted limit requests. Upgrade your plan.
500 Internal Server Error Server error. You should never see that ones. If you do please .

GET - All data

Returns an array with all data from spreadsheet.

curl https://sheetdb.io/api/v1/58f61be4dda40 $url = 'https://sheetdb.io/api/v1/58f61be4dda40'; $options = array( 'http' => array( 'method' => 'GET' ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
[
  {
    "id": "1",
    "name": "Tom",
    "age": "41"
  },
  {
    "id": "2",
    "name": "Alex",
    "age": "24"
  },
  {
    "id": "3",
    "name": "John",
    "age": "51"
  },
  {
    "id": "61",
    "name": "Steve",
    "age": "22",
    "comment": "special"
  },
  {
    "id": "422",
    "name": "James",
    "age": "19"
  }
]

GET - Keys

Returns an array with all keys from spreadsheet = values of first row inside document.

curl https://sheetdb.io/api/v1/58f61be4dda40/keys $url = 'https://sheetdb.io/api/v1/58f61be4dda40/keys'; $options = array( 'http' => array( 'method' => 'GET' ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
[
  "id",
  "name",
  "age",
  "comment"
]

GET - Document name

Returns a spreadsheet document name.

curl https://sheetdb.io/api/v1/58f61be4dda40/name $url = 'https://sheetdb.io/api/v1/58f61be4dda40/name'; $options = array( 'http' => array( 'method' => 'GET' ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
{
  "name": "SheetDB test document"
}

GET - List of available sheets

Returns a list of all available sheets (tabs).

curl https://sheetdb.io/api/v1/58f61be4dda40/sheets $url = 'https://sheetdb.io/api/v1/58f61be4dda40/sheets'; $options = array( 'http' => array( 'method' => 'GET' ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
{
  "sheets": [
    "Sheet1",
    "Sheet2"
  ]
}

GET - Count

Returns a number of rows is document (without first row).

curl https://sheetdb.io/api/v1/58f61be4dda40/count $url = 'https://sheetdb.io/api/v1/58f61be4dda40/count'; $options = array( 'http' => array( 'method' => 'GET' ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
{
  "rows": 5
}

GET - Search OR in document

The same as # GET - Search but if any parameter succed to match, it will be listed in response

By default search is not case sensitive, however if you specify optional parameter casesensitive to true, the search will be case sensitive.

If you want to search for something with spacebar, just repace space with %20

curl https://sheetdb.io/api/v1/58f61be4dda40/search_or?name=Steve&age=19&casesensitive=true $url = 'https://sheetdb.io/api/v1/58f61be4dda40/search_or?name=Steve&age=19&casesensitive=true'; $options = array( 'http' => array( 'method' => 'GET' ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
[
  {
    "id": "61",
    "name": "Steve",
    "age": "22",
    "comment": "special"
  },
  {
    "id": "422",
    "name": "James",
    "age": "19"
  }
]

POST - Create row

Create rows in document. JSON should have key data - it should be an array of rows. Keys inside array should be a column names (see # GET - keys) and values will be values inside spreadsheet. Rows will be added to the end of spreadsheet. If you want to add a single row simply send an array with one item {data: [{id:5,name:"Frank"}]}). If success API returns count of created with status code 201 Created

curl -X POST -H "Content-Type: application/json" https://sheetdb.io/api/v1/58f61be4dda40 -d '{"data":[{ "name": "Scott", "age": "25" }]}' $url = 'https://sheetdb.io/api/v1/58f61be4dda40'; $data = http_build_query( [ 'data' => [ ['name' => 'Scott', 'age' => 25] ] ] ); $options = array( 'http' => array( 'method' => 'POST', 'header' => 'Content-type: application/x-www-form-urlencoded', 'content' => $data ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
{
  "created":1
}

PATCH

Update row(s) for given column and value. Similar to # GET - Search you need to specify key (column name) and value to find. Any rows that matches a condition will be updated.

Note that PATCH requests will update only values passed in data object. If you want to replace entire row check out # PUT

It returns count of updated rows.

curl -X PATCH -H "Content-Type: application/json" https://sheetdb.io/api/v1/58f61be4dda40/{column}/{value} -d '{"data":[{ "name": "Scott", "age": "25" }]}' $url = 'https://sheetdb.io/api/v1/58f61be4dda40/{column}/{value}'; $data = http_build_query( [ 'data' => [ ['name' => 'Scott', 'age' => 25] ] ] ); $options = array( 'http' => array( 'method' => 'PATCH', 'header' => 'Content-type: application/x-www-form-urlencoded', 'content' => $data ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
{
  "updated":1
}

PUT

Update row(s) for given column and value. Similar to # GET - Search you need to specify key (column name) and value to find. Any rows that matches a condition will be updated.

Note that PUT requests will update entire row - some fields might get emptied. If you want to update only passed by values check out # PATCH

It returns count of updated rows.

curl -X PUT -H "Content-Type: application/json" https://sheetdb.io/api/v1/58f61be4dda40/{column}/{value} -d '{"data":[{ "name": "Scott", "age": "25" }]}' $url = 'https://sheetdb.io/api/v1/58f61be4dda40/{column}/{value}'; $data = http_build_query( [ 'data' => [ ['name' => 'Scott', 'age' => 25] ] ] ); $options = array( 'http' => array( 'method' => 'PUT', 'header' => 'Content-type: application/x-www-form-urlencoded', 'content' => $data ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
{
  "updated":1
}

DELETE

Delete row(s) for given column and value. Similar to # GET - Search you need to specify key (column name) and value to find. Any rows that matches a condition will be deleted.

It returns count of deleted rows.

curl -X PUT -H "Content-Type: application/json" https://sheetdb.io/api/v1/58f61be4dda40/{column}/{value} -d '{"data":[{ "name": "Scott", "age": "25" }]}' $url = 'https://sheetdb.io/api/v1/58f61be4dda40/{column}/{value}'; $options = array( 'http' => array( 'method' => 'DELETE' ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
{
  "deleted":1
}

Multiple Sheets

You don't have to specify sheet - by default the first sheet (tab) is selected.

To select other sheets you need to pass a sheet parameter wtih sheet name to request. You can add it to any of RESTful requests.

When sheet is not found you'll get 404 error.

curl https://sheetdb.io/api/v1/58f61be4dda40?sheet=Sheet2 $url = 'https://sheetdb.io/api/v1/58f61be4dda40?sheet=Sheet2'; $options = array( 'http' => array( 'method' => 'GET' ) ); $result = json_decode( file_get_contents($url, false, stream_context_create($options)) );
[
  {
    "player": "Smith",
    "score": "41"
  },
  {
    "player": "Martha",
    "score": "43"
  },
  {
    "player": "Craig",
    "score": "12"
  },
  {
    "player": "Michael",
    "score": "61"
  }
]

API Rate Limits

After you hit your rate limit, your requests will recive 429 Too Many Requests. You can check limits or upgrade account in pricing page.

We are here for you!

If you have any questions please feel free to ask via email or inapp chat.