NAV Navbar
Logo
cURL HTML Snippet Ruby Node JavaScript Web Client Python PHP JQuery C# Swift

Introduction

Edit on GitHub

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

Community libraries

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
client.read().then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});
// Read first two rows from sheet "Sheet2"
client.read({ limit: 2, sheet: "Sheet2" }).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});
<head>
  <script src="//script.sheetsu.com/"></script>
</head>
<body>
  <script>
    function successFunc(data) {
      console.log(data);
    }
    Sheetsu.read("https://sheetsu.com/apis/v1.0/020b2c0f/", {}, successFunc);
  </script>
</body>
from sheetsu import SheetsuClient
client = SheetsuClient("020b2c0f")
# Read first two rows from sheet "Sheet2"
client.read(sheet="Sheet2", limit=2)
<?php

require('vendor/autoload.php');
use Sheetsu\Sheetsu;

$sheetsu = new Sheetsu([
    'sheetId' => '020b2c0f'
]);


// Read whole spreadsheet
$response = $sheetsu->read();
$collection = $response->getCollection();


// Read first two rows from sheet "Sheet2"
$response = $sheetsu->sheet('Sheet2')->read(2, 0);
$collection = $response->getCollection();

?>
function successFunc(data) {
  console.log(data);
}

// Read whole spreadsheet
var url = "https://sheetsu.com/apis/v1.0/020b2c0f";
$.ajax({ url: url, success: successFunc });


// Read first two rows from sheet "Sheet2"
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2";
var params = { "limit": 2 };
$.ajax({ url: url, data: params, success: successFunc });

using System;
using System.Net;
using System.IO;

namespace Sheetsu
{
    public class Example
    {
        public static void Main(string[] args)
        {
            string sheetsuResponse = string.Empty;
            string apiUrl = @"https://sheetsu.com/apis/v1.0/020b2c0f";

            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(apiUrl);
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();

            Stream stream = response.GetResponseStream();
            StreamReader reader = new StreamReader(stream);
            sheetsuResponse = reader.ReadToEnd();
        }
    }
}
import Foundation

// Read whole spreadsheet
let url = String(format: "https://sheetsu.com/apis/v1.0/020b2c0f")
let serviceUrl = URL(string: url)
var request = URLRequest(url: serviceUrl!)

request.httpMethod = "GET"
request.setValue("Application/json", forHTTPHeaderField: "Content-Type")

let session = URLSession.shared

session.dataTask(with: request) { (data, response, error) in
  if let data = data {
    do {
      let json = try JSONSerialization.jsonObject(with: data, options: [])
      print(json)
    } catch {
      print(error)
    }
  }
}.resume()

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);
});
<head>
  <script src="//script.sheetsu.com/"></script>
</head>
<body>
  <script>
    function successFunc(data) {
      console.log(data);
    }
    // Get all rows where column 'score' is '42'
    var searchQuery = {
      score: 42,
    };
    Sheetsu.read("https://sheetsu.com/apis/v1.0/020b2c0f/", {
      search: searchQuery
    }, successFunc);
  </script>
</body>
from sheetsu import SheetsuClient
client = SheetsuClient("020b2c0f")
# Get all rows where column 'score' is '42'
client.search(score="42")
# Get all rows where column 'score' is '42'
# and column 'name' is 'Peter'
client.search(score="42", name="Peter")
# Get first two rows where column 'foo' is 'bar'
# from sheet "Sheet2"
client.search(sheet="Sheet2", foo="bar", limit=2)
# Get all rows where column 'name' is contains string 'oi'
client.search(name="*oi*")
<?php

require('vendor/autoload.php');
use Sheetsu\Sheetsu;

$sheetsu = new Sheetsu([
    'sheetId' => '020b2c0f'
]);


// Get all rows where column 'score' is '42'
$response = $sheetsu->search([
    'score' => '42'
]);
$collection = $response->getCollection();


// Get all rows where column 'score' is '42'
// and column 'name' is 'Peter'
$response = $sheetsu->search([
    'name' => 'Peter',
    'score'      => '42'
]);
$collection = $response->getCollection();


// Get first two rows where column 'foo' is 'bar'
// from sheet "Sheet2"
$response = $sheetsu->sheet('Sheet2')->search([
    'foo' => 'bar',
], 2, 0);
$collection = $response->getCollection();


// Get all rows where column 'name' is contains string 'oi'
$response = $sheetsu->search([
    'name' => '*oi*',
]);
$collection = $response->getCollection();

?>
function successFunc(data) {
  console.log(data);
}

// Read whole spreadsheet
$.ajax({ url: url, success: successFunc });


// Get all rows where column 'score' is '42'
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/search";
var params = { "score": 42 };
$.ajax({ url: url, data: params, success: successFunc });


// Get all rows where column 'score' is '42'
// and column 'name' is 'Peter'
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/search";
var params = { "score": 42, "name": "Peter" };
$.ajax({ url: url, data: params, success: successFunc });


// Get first two rows where column 'foo' is 'bar'
// from sheet "Sheet2"
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2/search";
var params = { "foo": "bar" };
$.ajax({ url: url, data: params, success: successFunc });


// Get all rows where column 'name' is contains string 'oi'
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/search";
var params = { "name": "*oi*" };
$.ajax({ url: url, data: params, success: successFunc });
using System;
using System.Net;
using System.IO;

namespace Sheetsu
{
    public class Example
    {
        public static void Main(string[] args)
        {
            string sheetsuResponse = string.Empty;
            string apiUrl = @"https://sheetsu.com/apis/v1.0/020b2c0f/search?score=42";

            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(apiUrl);
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();

            Stream stream = response.GetResponseStream();
            StreamReader reader = new StreamReader(stream);
            sheetsuResponse = reader.ReadToEnd();
        }
    }
}
import Foundation

// Get all rows where column 'score' is '42'
let url = String(format: "https://sheetsu.com/apis/v1.0/020b2c0f/search?score=42")
let serviceUrl = URL(string: url)
var request = URLRequest(url: serviceUrl!)
request.httpMethod = "GET"
request.setValue("Application/json", forHTTPHeaderField: "Content-Type")

let session = URLSession.shared

session.dataTask(with: request) { (data, response, error) in
  if let data = data {
    do {
      let json = try JSONSerialization.jsonObject(with: data, options: [])
      print(json)
    } catch {
      print(error)
    }
  }
}.resume()

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" }
]
client.create(rows).then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});
// Adds single row to sheet named "Sheet2"
client.create({ "foo": "bar", "another column": "quux" }, "Sheet2").then(function(data) {
  console.log(data);
}, function(err){
  console.log(err);
});
<head>
  <script src="//script.sheetsu.com/"></script>
</head>
<body>
  <form id="myForm">
    <input type="text" name="first_name">
    <input type="text" name="score">
    <button type="submit">Save</button>
  </form>
  <script>
    document.querySelector("#myForm").addEventListener("submit", function (e) {
      e.preventDefault();
      saveData();
    });
    function saveData() {
      var first_name = document.getElementsByName("first_name")[0].value,
        score = document.getElementsByName("score")[0].value;
      var data = {
        name: first_name,
        score: score
      };
      Sheetsu.write("https://sheetsu.com/apis/v1.0/020b2c0f/", data, {}, function (result) {
        console.log(result);
      });
    }
  </script>
</body>
from sheetsu import SheetsuClient
client = SheetsuClient("020b2c0f")
# Adds single row to spreadsheet
client.create_one(id="7", name="Glenn", score="96")
# Adds single row to spreadsheet to sheet named "Sheet2"
client.create_one(sheet="Sheet2", foo="quux")
# Adds bunch of rows to spreadsheet to sheet named "Sheet1"
client.create_many(
  sheet="Sheet1",
  *[
    dict(id="8", name="Brian", score="42"),
    dict(id="9", name="Joe", score="201")
  ]
)
<?php

require('vendor/autoload.php');
use Sheetsu\Sheetsu;

$sheetsu = new Sheetsu([
    'sheetId' => '020b2c0f'
]);


// Adds single row to spreadsheet
$sheetsu->create([['id' => '7', 'name' => 'Glenn', 'score' => 96 ]]);


// Adds single row to spreadsheet to sheet named "Sheet2"
$sheetsu->sheet('Sheet2')->create([['id' => '8', 'name' => 'Glenn', 'score' => 96 ]]);


// Adds bunch of rows to spreadsheet
$sheetsu->create([
  [ 'id' => '7', 'name' => 'Glenn', 'score' => '69' ],
  [ 'id' => '8', 'name' => 'Brian', 'score' => '77' ],
  [ 'id' => '9', 'name' => 'Joe', 'score' => '45' ]
]);

?>
function successFunc(data) {
  console.log(data);
}

// Adds single row to spreadsheet
var url = "https://sheetsu.com/apis/v1.0/020b2c0f";
var params = { id: 7, name: 'Glenn', score: 96 };
$.ajax({ type: "POST", url: url, data: params, success: successFunc });


// Adds single row to spreadsheet to sheet named "Sheet2"
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2";
var params = { id: 7, name: 'Glenn', score: 96 };
$.ajax({ type: "POST", url: url, data: params, success: successFunc });


// Adds bunch of rows to spreadsheet
var url = "https://sheetsu.com/apis/v1.0/020b2c0f";
var params = JSON.stringify({
  rows: [
    { id: 7, name: 'Glenn', score: 96 },
    { id: 8, name: 'Brian', score: 77 },
    { id: 9, name: 'Joe', score: 45 }  
  ]
});
$.ajax(
  {
    type: "POST", url: url, data: params, success: successFunc,
    contentType: 'application/json', processData: false
  }
);
using System;
using System.Net;
using System.IO;

namespace Sheetsu
{
    public class Example
    {
        public static void Main(string[] args)
        {
            string apiUrl = @"https://sheetsu.com/apis/v1.0/020b2c0f";
            string sheetsuResponse = string.Empty;

            HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create(apiUrl);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "POST";

            StreamWriter streamWriter = new StreamWriter(httpWebRequest.GetRequestStream());
            string json = "{\"id\":\"6\", \"name\": \"Glenn\", \"score\": \"1000\"}";

            streamWriter.Write(json);
            streamWriter.Flush();
            streamWriter.Close();

            HttpWebResponse response = (HttpWebResponse)httpWebRequest.GetResponse();
            StreamReader reader = new StreamReader(response.GetResponseStream());

            sheetsuResponse = reader.ReadToEnd();
        }
    }
}
import Foundation

// Adds single row to spreadsheet
let url = String(format: "https://sheetsu.com/apis/v1.0/020b2c0f")
let serviceUrl = URL(string: url)
let parameterDictionary = ["id" : "6", "name" : "Glenn", "score": "44"]
var request = URLRequest(url: serviceUrl!)

request.httpMethod = "POST"
request.setValue("Application/json", forHTTPHeaderField: "Content-Type")

let httpBody = try? JSONSerialization.data(withJSONObject: parameterDictionary, options: [])

request.httpBody = httpBody

let session = URLSession.shared

session.dataTask(with: request) { (data, response, error) in
  if let data = data {
    do {
      let json = try JSONSerialization.jsonObject(with: data, options: [])
      print(json)
    } catch {
      print(error)
    }
  }
}.resume()

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);
});
from sheetsu import SheetsuClient
client = SheetsuClient("020b2c0f")
# Update all rows where value of column name is Peter
# Update only score column
client.update(column="name", value="Peter", data=dict(score=120)))
# Update all rows where value of column name is Peter
# Update only score column
client.update(column="name", value="Peter", data=dict(score=120)))
<?php

require('vendor/autoload.php');
use Sheetsu\Sheetsu;

$sheetsu = new Sheetsu([
    'sheetId' => '020b2c0f'
]);

// Update all rows where value of column name is Peter
// Update only score column
$sheetsu->update('name', 'Peter', ['score' => '120']);


// Update all rows where value of column name is Peter
// Update whole row
$sheetsu->update('name', 'Peter', ['id' => 2, 'name' => 'Loo1z', 'score' => '99999'], true);

?>
function successFunc(data) {
  console.log(data);
}

// Update all rows where value of column name is Peter
// Update only score column
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/name/Peter";
var params = { score: 120 };
$.ajax({ type: "PATCH", url: url, data: params, success: successFunc });


// Update all rows where value of column name is Peter
// Update whole row
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/name/Peter";
var params = { id: 2, name: 'Loo1z', score: '99999' };
$.ajax({ type: "PUT", url: url, data: params, success: successFunc });
using System;
using System.Net;
using System.IO;

namespace Sheetsu
{
    public class Example
    {
        public static void Main(string[] args)
        {
            string apiUrl = @"https://sheetsu.com/apis/v1.0/020b2c0f/name/Peter";
            string sheetsuResponse = string.Empty;

            HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create(apiUrl);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "PATCH";

            StreamWriter streamWriter = new StreamWriter(httpWebRequest.GetRequestStream());
            string json = "{\"score\": \"9999\"}";

            streamWriter.Write(json);
            streamWriter.Flush();
            streamWriter.Close();

            HttpWebResponse response = (HttpWebResponse)httpWebRequest.GetResponse();
            StreamReader reader = new StreamReader(response.GetResponseStream());

            sheetsuResponse = reader.ReadToEnd();
        }
    }
}
import Foundation

// Update all rows where value of column name is Peter
let url = String(format: "https://sheetsu.com/apis/v1.0/020b2c0f/name/Peter")
let serviceUrl = URL(string: url)

// Update only score column
let parameterDictionary = ["score": "1337"]
var request = URLRequest(url: serviceUrl!)

request.httpMethod = "PATCH"
request.setValue("Application/json", forHTTPHeaderField: "Content-Type")

let httpBody = try? JSONSerialization.data(
  withJSONObject: parameterDictionary,
  options: []
)

request.httpBody = httpBody

let session = URLSession.shared

session.dataTask(with: request) { (data, response, error) in
  if let data = data {
    do {
      let json = try JSONSerialization.jsonObject(
        with: data,
        options: []
      )
      print(json)
    } catch {
      print(error)
    }
  }
}.resume()

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

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

Clear

# Clear all rows where name is Lois
curl "https://sheetsu.com/apis/v1.0/020b2c0f/name/Lois" \
-X DELETE
# Clear 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")
# Clear all rows where value of column name is Lois
sheetsu.delete(
  "name", # column name
  "Lois", # value to search for
)
# Clear 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' })
// Clear 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);
});
// Clear 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);
});
from sheetsu import SheetsuClient
client = SheetsuClient("020b2c0f")
# Clear all rows where value of column name is Peter
client.delete(column="name", value="Peter")
# Clear all rows from sheet named Sheet1
# where value of column name is Meg
client.delete(sheet="Sheet1", column="name", value="Meg")
<?php

require('vendor/autoload.php');
use Sheetsu\Sheetsu;

$sheetsu = new Sheetsu([
    'sheetId' => '020b2c0f'
]);


// Clear all rows where value of column name is Peter
$sheetsu->delete('name', 'Peter');


// Clear all rows from sheet named Sheet1
// where value of column name is Meg
$sheetsu->sheet('Sheet1')->delete('name', 'Meg');

?>
function successFunc(data) {
  console.log(data);
}

// Clear all rows where value of column name is Peter
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/name/Peter";
$.ajax({ type: "DELETE", url: url, success: successFunc });


// Clear all rows from sheet named Sheet1
// where value of column name is Meg
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet1/name/Meg";
$.ajax({ type: "DELETE", url: url, success: successFunc });
using System;
using System.Net;
using System.IO;

namespace Sheetsu
{
    public class Example
    {
        public static void Main(string[] args)
        {
            string apiUrl = @"https://sheetsu.com/apis/v1.0/020b2c0f/name/Peter";
            string sheetsuResponse = string.Empty;

            HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create(apiUrl);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "DELETE";

            HttpWebResponse response = (HttpWebResponse)httpWebRequest.GetResponse();
            StreamReader reader = new StreamReader(response.GetResponseStream());

            sheetsuResponse = reader.ReadToEnd();
        }
    }
}
import Foundation

// Clear all rows where value of column name is Peter
let url = String(format: "https://sheetsu.com/apis/v1.0/020b2c0f/name/Peter")
let serviceUrl = URL(string: url)
var request = URLRequest(url: serviceUrl!)

request.httpMethod = "DELETE"
request.setValue("Application/json", forHTTPHeaderField: "Content-Type")

let session = URLSession.shared

session.dataTask(with: request) { (data, response, error) in
  if let data = data {
    do {
      let json = try JSONSerialization.jsonObject(
        with: data,
        options: []
      )
      print(json)
    } catch {
      print(error)
    }
  }
}.resume()

Send DELETE request with a /{column_name}/{value} path added at the end of the URL to delete row(s). Clear row(s) where {column_name} match {value}. Clear doesn’t change the number of rows.

Returns

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

Destroy

# Destroy all rows where column 'name' is 'Lois'
curl "https://sheetsu.com/apis/v1.0/020b2c0f" \
-X DELETE \
-H "Content-Type: application/json" \
-d '{ "name": "Lois" }'
# Destroy all rows where column 'score' is '42'
# and column 'name' is 'Peter'
curl "https://sheetsu.com/apis/v1.0/020b2c0f" \
-X DELETE \
-H "Content-Type: application/json" \
-d '{ "score": "42", "name": "Peter" }'
# Destroy all rows from sheet 'Sheet2'
# where column 'score' is '42' and column 'name' is 'Peter'
curl "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2" \
-X DELETE \
-H "Content-Type: application/json" \
-d '{ "score": "42", "name": "Peter" }'
# Destroy all rows where column 'name' is starting with 'p' or 'P'
curl "https://sheetsu.com/apis/v1.0/020b2c0f" \
-X DELETE \
-H "Content-Type: application/json" \
-d '{ "name": "p*", "ignore_case": "true" }'
# Destroy all rows where column 'name' contains string 'oi'
curl "https://sheetsu.com/apis/v1.0/020b2c0f" \
-X DELETE \
-H "Content-Type: application/json" \
-d '{ "name": "*oi*" }'
function successFunc(data) {
  console.log(data);
}

// Destroy all rows where column 'name' is 'Lois'
var url = "https://sheetsu.com/apis/v1.0/020b2c0f";
var params = { name: "Lois" }
$.ajax({ type: "DELETE", url: url, data: params, success: successFunc });


// Destroy all rows where column 'score' is '42'
// and column 'name' is 'Peter'
var url = "https://sheetsu.com/apis/v1.0/020b2c0f";
var params = { score: 42, name: "Peter" }
$.ajax({ type: "DELETE", url: url, data: params, success: successFunc });


// Destroy all rows from sheet 'Sheet2'
// where column 'score' is '42' and column 'name' is 'Peter'
var url = "https://sheetsu.com/apis/v1.0/020b2c0f/sheets/Sheet2";
var params = { score: 42, name: "Peter" }
$.ajax({ type: "DELETE", url: url, data: params, success: successFunc });


// Destroy all rows where column 'name' is starting with 'p' or 'P'
var url = "https://sheetsu.com/apis/v1.0/020b2c0f";
var params = { name: "p*", ignore_case: true }
$.ajax({ type: "DELETE", url: url, data: params, success: successFunc });


// Destroy all rows where column 'name' contains string 'oi'
var url = "https://sheetsu.com/apis/v1.0/020b2c0f";
var params = { name: "*oi*" }
$.ajax({ type: "DELETE", url: url, data: params, success: successFunc });

Send DELETE request to destroy all matched rows, move up below rows and decrease number of rows. Pass params in a column_name=value as params to the request.

Wildcard matching

You can match rows to destroy using wildcards (*). Asteriks (*) can represent any characters or empty string.

Request Parameters

You can optionally ignore letter case sensitivity.

Parameter Description
ignore_case Ignore letter case sensitivity. Both column names and values

Returns

On success, returns 200 OK HTTP status code, with all destroyed rows at 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:

IdNameScore
1Peter42
2Lois89
3Meg10
<!--
  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

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

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:

  1. Add sheetsu attribute to the <form> element.
  2. 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.

Creating API programmatically

# Creates new API
curl "https://sheetsu.com/apis/v1.0/api_sheets" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "email": "your@email.com", "api_key": "api_key", "google_spreadsheet_url": "your_doc_url" }'

API can be created by sending POST request to https://sheetsu.com/apis/v1.0/api_sheets. This feature is not available in all plans - check pricing page to know more. Please contact support to get your api_key.

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/.