Introduction

Welcome

You can view code examples in the area on the right. You can switch the programming language with the tabs in the top right. We provide examples in cURL, Ruby and some of them with our Snippet - which is pure HTML.

Follow @sheetsuhq on Twitter for latest updates and news.

SDKs & Client libraries

Official libraries

Ruby: https://github.com/sheetsu/sheetsu-ruby
Node: https://github.com/sheetsu/sheetsu-node

Community libraries

PHP: https://github.com/emilianozublena/sheetsu-php

How to prepare spreadsheet

Every spreadsheet should have the first row populated with column names. There are no mandatory fields or values you need to have in your spreadsheet. The structure of the spreadsheet is totally up to you. Just keep in mind, that the first row (row #1) is treated as there are column names.

Column names can be anything. Strings, numbers, symbols, emojis 🙉 , anything.

You can check example spreadsheet here. It looks like this:

Example Spredsheet for Sheetsu.com

id	name	score
1	Peter	42
2	Lois	89
3	Meg	10
4	Chris	42
5	Stewie	72

Google Spreadsheet URL

To properly use Sheetsu, please paste Google Spreadsheets URL. Just copy the URL from the browser address bar. There’s no need for sharing the Google Spreadsheet.

Google Chrome

Spreadsheet URL in Google Chrome

Safari

Spreadsheet URL in Safari

About the API

The Sheetsu API is meant to provide a RESTful way to interact with a Google Spreadsheets. Our API uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP Basic authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

We support cross-origin resource sharing. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

The requests in the right sidebar are designed to work as is. The sample requests are performed using our test API and test spreadsheet, which you can find here.

Core

Edit on GitHub

READ

Read all data

# Read whole spreadsheet
curl "https://sheetsu.com/apis/v1.0/020b2c0f"

# Read first two rows from sheet "Sheet2"
curl "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2?limit=2"

<!-- Read whole spreadsheet -->
<div sheetsu="https://sheetsu.com/apis/v1.0/020b2c0f">
  <p>Name: {{name}}</p>
  <p>Score: {{score}}</p>
</div>

<script src="//load.sheetsu.com"></script>

<!-- Read first two rows from sheet "Sheet1" -->
<div sheetsu="https://sheetsu.com/apis/v1.0/020b2c0f" sheetsu-limit="2" sheetsu-sheet="Sheet1">
  <p>Name: {{name}}</p>
  <p>Score: {{score}}</p>
</div>

<script src="//load.sheetsu.com"></script>

require 'sheetsu'
sheetsu = Sheetsu::Client.new("020b2c0f")

# Read whole spreadsheet
sheetsu.read

# Read first two rows from sheet "Sheet2"
sheetsu.read(sheet: "Sheet2", limit: 2)

var sheetsu = require('sheetsu-node')
// import sheetsu from 'sheetsu-node' for ES6
var client = sheetsu({ address: '020b2c0f' })

// Read whole spreadsheet
sheetsu.read().then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

// Read first two rows from sheet "Sheet2"
sheetsu.read({ limit: 2, sheet: "Sheet2" }).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

API can return whole Google Spreadsheet via a GET method to https://sheetsu.com/apis/v1.0/{id}.

Request Parameters

You can optionally limit results, or start with offset.

Parameter	Description
limit	Number of how many rows should be returned
offset	Number from which row response should start (default is 0)

Returns

An array of objects. Each object is a row from the Google Spreadsheet.

Search spreadsheet

# Get all rows where column 'score' is '42'
curl "https://sheetsu.com/apis/v1.0/020b2c0f/search?score=42"

# Get all rows where column 'score' is '42'
# and column 'name' is 'Peter'
curl "https://sheetsu.com/apis/v1.0/020b2c0f/search?score=42&name=Peter"

# Get first two rows where column 'foo' is 'bar',
# column 'another column' is '1' from sheet "Sheet2"
curl "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2/search?foo=bar&another%20column=1&limit=2"

# Get all rows where column 'name' is starting with 'p'
curl "https://sheetsu.com/apis/v1.0/020b2c0f/search?name=p*&ignore_case=true"

# Get all rows where column 'name' is contains string 'oi'
curl "https://sheetsu.com/apis/v1.0/020b2c0f/search?name=*oi*"

<!-- Get all records where score is 42 -->
<div sheetsu="https://sheetsu.com/apis/v1.0/020b2c0f" sheetsu-search='{"score": "42"}'>
  <p>Name: {{name}}, score: {{score}}</p>
</div>

<script src="//load.sheetsu.com"></script>

<!--
  Get all records where score is 42
  from sheet "Sheet1"
-->
<div sheetsu="https://sheetsu.com/apis/v1.0/020b2c0f" sheetsu-search='{"score": "42"}' sheetsu-sheet="Sheet1">
  <p>Name: {{name}}, score: {{score}}</p>
</div>

<script src="//load.sheetsu.com"></script>

require 'sheetsu'
sheetsu = Sheetsu::Client.new("020b2c0f")

# Get all rows where column 'score' is '42'
sheetsu.read(search: { score: 42 })

# Get all rows where column 'score' is '42'
# and column 'name' is 'Peter'
sheetsu.read(search: { score: 42, name: "Peter" })

# Get first two rows where column 'foo' is 'bar',
# column 'another column' is '1' from sheet "Sheet2"
sheetsu.read(
  # search criteria
  search: { "foo" => "bar", "another column" => "1" },
  limit: 2,       # first two rows
  sheet: "Sheet2" # Sheet name
)

var sheetsu = require('sheetsu-node')
// import sheetsu from 'sheetsu-node' for ES6
var client = sheetsu({ address: '020b2c0f' })

// Get all rows where column 'score' is '42'
client.read({ search: { score: 42 } }).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

// Get all rows where column 'score' is '42'
// and column 'name' is 'Peter'
client.read({ search: { score: 42, name: "Peter" } }).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

// Get first two rows where column 'foo' is 'bar',
// column 'another column' is '1' from sheet "Sheet2"
client.read({
  limit: 2, // first two rows
  // search criteria
  search: { "foo": "bar", "another column": "1" },
  sheet: "Sheet2" // Sheet name
}
).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

Search Google Spreadsheet for particular records. Pass params in a column_name=value as params to the GET https://sheetsu.com/apis/v1.0/{id}/search request.

Wildcard searching

You can search using wildcards (*). Asteriks (*) can represent any characters or empty string.

Request Parameters

You can optionally limit results, or start with offset.

Parameter	Description
limit	Number of how many rows should be returned
offset	Number from which row response should start (default is 0)
ignore_case	Ignore letter case sensitivity. Both column names and values

Returns

An array of objects. Each object is a row from the Google Spreadsheet.

CREATE

# Adds one row to spreadsheet
curl "https://sheetsu.com/apis/v1.0/020b2c0f" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "id": "6", "name": "Glenn", "score": "69" }'

# Add multiple rows in one request
curl "https://sheetsu.com/apis/v1.0/020b2c0f" \
-X POST \
-H "Content-Type: application/json" \
-d '
{
  "rows": [
    { "id": "6", "name": "Glenn", "score": "69" },
    { "id": "7", "name": "Joe", "score": "98" }
  ]
}'

# Adds single row to sheet named "Sheet2"
curl "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "foo": "6", "another column": "quux" }'

<!--
  Display form, which will
  save record to the Google Spreadsheet
-->
<form sheetsu="https://sheetsu.com/apis/v1.0/1c3c0ff33">
  <input type="text" name="full_name">
  <input type="text" name="email">
  <textarea name="message"></textarea>

  <input type="submit">
</form>

<script src="//load.sheetsu.com"></script>

<!--
  Display form, which will
  save record to the Google Spreadsheet
  to sheet "Sheet1"
-->
<form sheetsu="https://sheetsu.com/apis/v1.0/1c3c0ff33" sheetsu-sheet="Sheet1">
  <input type="text" name="full_name">
  <input type="text" name="email">
  <textarea name="message"></textarea>

  <input type="submit">
</form>

<script src="//load.sheetsu.com"></script>

require 'sheetsu'
sheetsu = Sheetsu::Client.new("020b2c0f")

# Adds single row to spreadsheet
sheetsu.create({ id: 7, name: "Glenn", score: "69" })

# Adds bunch of rows to spreadsheet
rows = [
  { id: 7, name: "Glenn", score: "69" },
  { id: 8, name: "Brian", score: "77" },
  { id: 9, name: "Joe", score: "45" }
]
sheetsu.create(rows)

# Adds single row to sheet named "Sheet2"
sheetsu.create({ "foo" => "bar", "another column" => "quux" }, "Sheet2")

var sheetsu = require('sheetsu-node')
// import sheetsu from 'sheetsu-node' for ES6
var client = sheetsu({ address: '020b2c0f' })

// Adds single row to spreadsheet
client.create({ id: 7, name: "Glenn", score: "69" }).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

// Adds bunch of rows to spreadsheet
var rows = [
  { id: 7, name: "Glenn", score: "69" },
  { id: 8, name: "Brian", score: "77" },
  { id: 9, name: "Joe", score: "45" }
]
cllient.create(rows).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

// Adds single row to sheet named "Sheet2"
cllient.create({ "foo": "bar", "another column": "quux" }, "Sheet2").then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

Add a row to Google Spreadsheet by sending a JSON object via POST request.

Multiple rows

Send an array of objects wrapped in { "rows": YOUR_ARRAY_HERE } JSON to add multiple rows in one request.

Returns

An array of created objects.

UPDATE

# Update all rows where value of column name is Peter
# Update only score colum
curl "https://sheetsu.com/apis/v1.0/020b2c0f/name/Peter" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{ "score": "1337" }'

# Update all rows where value of column name is Lois
# Update whole row
curl "https://sheetsu.com/apis/v1.0/020b2c0f/name/Lois" \
-X PUT \
-H "Content-Type: application/json" \
-d '{ "id": "2", "name": "Loo1z", "score": "99999" }'

# Update all rows from sheet "Sheet2"
# where value of column foo is bar
# Update only baz colum
curl "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2/foo/bar" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{ "another column": "quux" }'

require 'sheetsu'
sheetsu = Sheetsu::Client.new("020b2c0f")

# Update all rows where value of column name is Peter
# Update only score column
sheetsu.update(
  "name",          # column name
  "Peter",         # value to search for
  { score: 1337 }, # hash with updates
)

# Update all rows where value of column name is Lois
# Update whole row
sheetsu.update(
  "name", # column name
  "Lois", # value to search for
   # hash with updates
  { "id": 2, "name" => "Loo1z", "score": 99999 },
  true # nullify all fields not passed in the hash above
)

# Update all rows from sheet "Sheet2"
# where value of column foo is bar
# Update only baz colum
# Empty all cells which are not 'score' or 'last name'
# (in other words, send PUT)
sheetsu.update(
  "foo", # column name
  "bar", # value to search for
  # hash with updates
  { "another column" => "quux" },
  false, # update only passed columns
  "Sheet2"
)

var sheetsu = require('sheetsu-node')
// import sheetsu from 'sheetsu-node' for ES6
var client = sheetsu({ address: '020b2c0f' })

// Update all rows where value of column name is Peter
// Update only score column
client.update(
  "name",          // column name
  "Peter",         // value to search for
  { score: 1337 } // hash with updates
).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

// Update all rows where value of column name is Lois
// Update whole row
client.update(
  "name", // column name
  "Lois", // value to search for
   // hash with updates
  { "id": 2, "name": "Loo1z", "score": 99999 },
  true // nullify all fields not passed in the hash above
).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

// Update all rows from sheet "Sheet2"
// where value of column foo is bar
// Update only baz colum
// Empty all cells which are not 'score' or 'last name'
// (in other words, send PUT)
client.update(
  "foo", // column name
  "bar", // value to search for
  // hash with updates
  { "another column": "quux" },
  false, // update only passed columns
  "Sheet2"
).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

Send PATCH (or PUT) request to update value(s) of a row(s). To identify the row(s) you want to update you need to add /{column_name}/{value} to the API URL. Then you need to pass JSON object with new values. Updates only rows where {column_name} match {value}.

Difference between `PUT` and `PATCH`

PUT request updates whole row. If you do not provide all fields in the JSON object, some fields might get emptied. PUT returns whole updated row(s).
PATCH request updates only values passed in JSON. Returns only updated fields.

Returns

An array of updated objects. If a request is sent via PATCH method returns only updated values. If a request is sent via PUT method returns only updated values.

DELETE

# Deletes all rows where name is Lois
curl "https://sheetsu.com/apis/v1.0/020b2c0f/name/Lois" \
-X DELETE

# Delete all rows from sheet "Sheet2"
# where value of column foo is bar
curl "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2/foo/bar" \
-X DELETE

require 'sheetsu'
sheetsu = Sheetsu::Client.new("020b2c0f")

# Delete all rows where value of column name is Lois
sheetsu.delete(
  "name", # column name
  "Lois", # value to search for
)

# Delete rows from sheet "Sheet2"
# where value of column foo is bar
sheetsu.delete(
  "foo",   # column name
  "bar",   # value to search for
  "Sheet2" # sheet name
)

var sheetsu = require('sheetsu-node')
// import sheetsu from 'sheetsu-node' for ES6
var client = sheetsu({ address: '020b2c0f' })

// Delete all rows where value of column name is Lois
client.delete(
  "name", // column name
  "Lois" // value to search for
).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

// Delete rows from sheet "Sheet2"
// where value of column foo is bar
client.delete(
  "foo",   // column name
  "bar",   // value to search for
  "Sheet2" // sheet name
).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});

Send DELETE request with a /{column_name}/{value} path added at the end of the URL to delete row(s). Deletes row(s) where {column_name} match {value}.

Returns

On success, returns 204 No Content HTTP status code, without a body.

Snippet

Edit on GitHub

The snippet is our “we are here for you” for all those, who don’t want to play with any programming languages or development but want to have all the Sheetsu super powers on their websites.

Snippet allows you to interact with a Google Spreadsheet from your website with just HTML.

Installation

Add below code before closing </body> tag.

<script src="//load.sheetsu.com"></script>

Hint

If you are using Google Analytics, add it right after the Google Analytics script.

Read data from Spreadsheet

<!--
  This code will get 3 first rows from
  Google Spreadsheet and display them
  in a table on a website
-->
<table>
  <thead>
    <th>Id</th>
    <th>Name</th>
    <th>Score</th>
  </thead>
  <tbody sheetsu="https://sheetsu.com/apis/v1.0/020b2c0f" sheetsu-limit="3">
    <tr>
      <td>{{id}}</td>
      <td>{{name}}</td>
      <td>{{score}}</td>
    </tr>
  </tbody>
</table>

<script src="//load.sheetsu.com"></script>

Above HTML will produce this result:

Id Name Score

1 Peter 42

2 Lois 89

3 Meg 10

<!--
  This code will get all rows from
  Google Spreadsheet where role is parent
  and display them with picture, name, email
-->
<div sheetsu="https://sheetsu.com/apis/v1.0/44317ab1d587" sheetsu-search='{"role": "parent"}'>
  <img src="{{picture_url}}">
  <p>
    Name: {{name}}
    <br>
    Email: {{email}}
  </p>
</div>

<script src="//load.sheetsu.com"></script>

Above HTML will produce this result:

Name:Peter Griffin
Email:peter@griffin.com

Name:Lois Griffin
Email:lois@griffin.com

Add sheetsu="YOUR_API_URL" to the parent element.
Add handlebars ( {{ and }} ) with column name to any child element, with column name.

Search

You can use an additional sheetsu-search attribute to show only results which are matching your search criteria.

The value of the sheetsu-search attribute should be a key-value object (JSON) with column name and value you want to use for search.

Remember to use single quote ' around JSON and double quote " with JSON key, value names.

Limit & offset

Attributes you can use to manipulate results are sheetsu-limit and sheetsu-offset.

(We add a little bit of CSS styling to the results on the right)

Save data to Spreadsheet

<!--
  This code will display form, which will
  save record to the Google Spreadsheet
  (check it here: )
-->
<form sheetsu="https://sheetsu.com/apis/v1.0/1c3c0ff33">
  <input type="text" name="full_name">
  <input type="text" name="email">
  <textarea name="message"></textarea>

  <input type="submit">
</form>

<script src="//load.sheetsu.com"></script>

Above HTML will produce this result:

Add sheetsu attribute to the <form> element.
Add <input> (or <textarea>) tags, where name attribute is column name from a spreadsheet.

After submit redirection

Optionally you can add sheetsu-after-submit attribute with the URL you want to redirect your users after they submit the form. Without this attribute, they get redirected to https://sheetsu.com/thank-you.html.

Other

Edit on GitHub

Multiple sheets

# Get whole spreadsheet from sheet named Sheet2
curl "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2"

# Adds single row to sheet named "Sheet2"
curl "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "foo": "6", "another column": "quux" }'

require 'sheetsu'
sheetsu = Sheetsu::Client.new("020b2c0f")

# Get whole spreadsheet from sheet named Sheet2
sheetsu.read(sheet: "Sheet2")

# Adds single row to sheet named "Sheet2"
sheetsu.create({ "foo" => "bar", "another column" => "quux" }, "Sheet2")

By default, always the first sheet (aka worksheet aka tab) is accessed. To access other sheets within a spreadsheet add /sheets/{sheet_name} path to the URL if using cURL, or pass appropriate param when using a lib.

Authentication

curl "https://sheetsu.com/apis/v1.0/020b2c0f" \
-u 'your_api_key:your_api_secret'

# Create new client object with HTTP Basic Auth keys
sheetsu = Sheetsu::Client.new(
  "020b2c0f",
  api_key: "YOUR_API_KEY",
  api_secret: "YOUR_API_SECRET"
)

You can secure your API with HTTP Basic authentication. It can be turned on in the API settings.

You have to send api_key and api_secret when you have authentication turned on.

Rate Limits

Every API has a rate limit. You can check rate limitś for APIs on the pricing page. After hitting the limit for the particular API, you receive 429 Rate limit exceeded status code.

HTTP Status Codes

Every response from the API is a JSON encoded string with a significant HTTP status code.

Code	Description
`200 OK`	Standard response for successful GET, PUT and PATCH requests
`201 Created`	Successful response for POST requests
`204 No Content`	Successful response for DELETE requests
`400 Bad Request`	Error response when creating (`POST`) or updating (`PUT`, `PATCH`) row(s)
`401 Unauthorized`	Error response when wrong authorization credentials provided
`402 Payment Required`	Returned if pro feature (multiple sheets) is tried to be accessed from free account
`403 Forbidden`	Error response when action is forbidden by the user (API owner)
`404 No such route`	Error response when route doesn’t exist
`429 Rate limit exceeded`	Error response when API hits quota exceeded
`500 Server error`

Each API URL has an id, which identifies it. It is part of the URL which is after https://sheetsu.com/apis/v1.0/.

Introduction

Welcome

SDKs & Client libraries

Official libraries

Community libraries

How to prepare spreadsheet

Google Spreadsheet URL

Google Chrome

Safari

About the API

Core

READ

Read all data

Request Parameters

Returns

Search spreadsheet

Wildcard searching

Request Parameters

Returns

CREATE

Multiple rows

Returns

UPDATE

Difference between PUT and PATCH

Returns

DELETE

Returns

Snippet

Installation

Hint

Read data from Spreadsheet

Search

Limit & offset

Save data to Spreadsheet

After submit redirection

Other

Multiple sheets

Authentication

Rate Limits

HTTP Status Codes

Difference between `PUT` and `PATCH`