# SheetDB

> SheetDB turns a Google Sheet into a JSON REST API. Sign in with Google, paste a spreadsheet URL and get an endpoint that reads, searches, adds, updates and deletes rows over HTTP, with no Google Cloud project, no OAuth code and built-in caching. Free plan available, no credit card required.

This is the long version of https://sheetdb.io/llms.txt. Website: https://sheetdb.io/. Documentation: https://docs.sheetdb.io/. Support: support@sheetdb.io or the chat on the website.

## How it works

1. Sign in at https://sheetdb.io/app with a Google account and grant SheetDB access to Google Sheets.
2. Click "Create new API" and paste the URL of an existing spreadsheet, or create a new spreadsheet from JSON.
3. SheetDB gives the API an id and an endpoint: `https://sheetdb.io/api/v1/{id}`.
4. The first row of the sheet is the header. Every other row is returned as a JSON object keyed by the header names. Values are strings unless `cast_numbers` is used.
5. Changes made in the spreadsheet show up in the API (after the cache expires) and rows written through the API appear in the spreadsheet.

SheetDB calls the official Google Sheets API on the user's behalf. It is a layer on top of Google Sheets, not a separate database: the data stays in the user's Google Drive.

Public demo API (resets every 15 minutes): `https://sheetdb.io/api/v1/58f61be4dda40`

```json
[
  { "id": "1", "name": "Tom",   "age": "15", "comment": "" },
  { "id": "2", "name": "Alex",  "age": "24", "comment": "" },
  { "id": "3", "name": "John",  "age": "51", "comment": "" },
  { "id": "4", "name": "Steve", "age": "22", "comment": "special" },
  { "id": "5", "name": "James", "age": "19", "comment": "" }
]
```

## API reference (summary)

Base URL: `https://sheetdb.io/api/v1/{id}`. Add `?sheet=TabName` to any request to work on another tab.

Read:

- `GET /api/v1/{id}`: all rows. Parameters: `limit`, `offset`, `sort_by`, `sort_order` (asc, desc, random), `cast_numbers=col1,col2` (return numbers instead of strings), `single_object=true` (return the first row as an object), `mode` (FORMATTED_VALUE, UNFORMATTED_VALUE, FORMULA).
- `GET /api/v1/{id}/keys`: column names. `GET /api/v1/{id}/count`: number of rows. `GET /api/v1/{id}/name`: spreadsheet name. `GET /api/v1/{id}/sheets`: tab names.
- `GET /api/v1/{id}/search?col=value&col2=value`: rows matching all conditions. `GET /api/v1/{id}/search_or?...`: rows matching any condition. Values support `*` wildcards, `!` negation and comparisons such as `age=>18` or `age=<30`. Search is case-insensitive by default; add `casesensitive=true` for exact case.
- `GET /api/v1/{id}/csv`: the sheet as CSV.
- `GET /api/v1/{id}/cells/A1,B2`: values of specific cells in A1 notation.
- Add `ignore_cache=1` to a read or search request to bypass the cache and read fresh data from Google.

Write:

- `POST /api/v1/{id}` with `{"data": [{...}, {...}]}`: append rows. Special values: `INCREMENT` (next number in the column), `TIMESTAMP`, `DATETIME`. Values are parsed as if typed into Google Sheets (USER_ENTERED); add `?mode=RAW` to POST, PATCH or PUT to store them exactly as sent.
- `PATCH /api/v1/{id}/{column}/{value}` with `{"data": {...}}`: update the given fields in every row where column equals value. `PUT` replaces the whole row.
- `PATCH` or `PUT /api/v1/{id}/batch_update`: update many rows in one request (paid plans).
- `DELETE /api/v1/{id}/{column}/{value}`: delete matching rows. `DELETE /api/v1/{id}/row_index/{n}`: delete a row by its 0-based position among the data rows (0 is the first row below the header). `DELETE /api/v1/{id}/all`: empty the tab. `DELETE /api/v1/{id}/duplicates`: remove duplicate rows.
- `POST /api/v1/{id}/import/json` with `{"json": [...]}` or `POST /api/v1/{id}/import/url` with `{"url": "..."}`: append rows from JSON.
- `POST` and `DELETE /api/v1/{id}/sheet`: create or delete a tab (Premium plan and above).

Example (JavaScript, works in the browser and in Node.js):

```js
const api = 'https://sheetdb.io/api/v1/58f61be4dda40';

const params = new URLSearchParams({ age: '>18' });
const adults = await fetch(`${api}/search?${params}`).then((response) => response.json());

await fetch(api, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: [{ id: 'INCREMENT', name: 'Mark', age: '35', comment: '' }] }),
});

await fetch(`${api}/id/4`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: { comment: 'renewed' } }),
});
```

Full reference: https://docs.sheetdb.io/sheetdb-api/read, /search, /create, /update, /delete, /other.

## Security and access control

- No authentication is required by default. Each API can enable a Bearer token or HTTP Basic auth (https://docs.sheetdb.io/authentication).
- Permissions switch read, create, update and delete on or off per API, e.g. a read-only API for a public website (https://docs.sheetdb.io/permissions).
- CORS origin restriction limits browser calls to chosen domains; an IP whitelist limits server calls to chosen addresses.
- The Google account connected to SheetDB must have access to the spreadsheet.

## Caching and limits

- Read responses are cached for 15 seconds by default. The duration can be increased in the API settings and the cache can be purged from the dashboard or a purge URL (https://docs.sheetdb.io/cache).
- Cached reads are answered without calling Google, which keeps busy sites within Google's Sheets API quotas (by default 60 read and 60 write requests per minute per user).
- Each plan has a monthly request quota; requests over the quota return HTTP 429 until the plan is upgraded or additional requests are bought. How requests are counted: https://docs.sheetdb.io/what-is-a-request.
- Rate limit: 90 requests per minute per API. The limit applies to the whole API, not to a single IP address, so all clients of one API share it; requests over it return HTTP 429 for up to a minute and the Retry-After header says how many seconds to wait. Details: https://docs.sheetdb.io/limits.
- Google's own limits apply to the spreadsheet: up to 10 million cells per spreadsheet and 50,000 characters per cell. A sheet used as a database works best below a few tens of thousands of rows.

## Plans

Pricing page: https://sheetdb.io/pricing

| Plan | Price | APIs | Requests/month |
|---|---|---|---|
| Free | Free forever, no credit card | 2 | 500 |
| Basic | $29.99/month, $25.49/month billed yearly | 5 | 10,000 |
| Premium | $49.99/month, $42.49/month billed yearly | 20 | 50,000 |
| Business | $129.99/month, $110.49/month billed yearly | 50 | 500,000 |
| Enterprise | from $399.99/month | Unlimited | Unlimited |

All plans include caching, custom permissions, CORS origin restriction, IP whitelist and the HTML snippet. Paid plans add batch update and help with integrations; Premium and above add tab management and global endpoints (create and list APIs programmatically); Business adds team accounts; Enterprise adds higher, individually negotiated rate limits on a separate enterprise instance, counted per customer rather than per API.

## Integrations and guides

- Websites: [display Google Sheets on a website](https://sheetdb.io/use-cases/display-google-sheets-on-website) with one script tag or fetch(); [HTML form to Google Sheets](https://sheetdb.io/use-cases/submit-to-google-sheets-with-html-form) without a backend.
- WordPress: [free plugin with shortcodes](https://sheetdb.io/use-cases/wordpress-with-google-sheets).
- Languages: [PHP](https://sheetdb.io/use-cases/google-sheets-json-data-with-php), [Node.js](https://sheetdb.io/use-cases/google-spreadsheet-data-with-node-js), and any language with an HTTP client.
- No-code: [Bubble](https://sheetdb.io/use-cases/bubble-with-google-sheets), [Adalo](https://sheetdb.io/use-cases/adalo-with-google-sheets), [n8n and Make](https://sheetdb.io/use-cases/n8n-make-with-google-sheets).
- Chatbots: [Dialogflow](https://sheetdb.io/use-cases/dialogflow-with-google-spreadsheet).
- Concepts: [Google Sheets as a database](https://sheetdb.io/solutions/google-sheets-as-database), [import JSON to Google Sheets](https://sheetdb.io/solutions/import-json-to-google-sheets).

## When SheetDB is not the right tool

- Formatting, charts, formulas across ranges or managing hundreds of spreadsheets: use the official Google Sheets API.
- Custom server-side logic or Google Workspace automation (emails, calendar, triggers): use Google Apps Script.
- High write concurrency, transactions, joins or millions of rows: use a real database.

## Comparisons

- [SheetDB vs Google Sheets API](https://sheetdb.io/compare/sheetdb-vs-google-sheets-api): The Google API is free and complete but is a developer tool that requires programming knowledge, needs a Google Cloud project, OAuth or a service account, returns arrays of cell values, has no value-based filtering and no caching, and defaults to 60 reads and 60 writes per minute per user. SheetDB returns JSON objects, searches on the server, caches reads and needs no Google Cloud setup, for a request-based plan with a free tier.
- [SheetDB vs Google Apps Script](https://sheetdb.io/compare/sheetdb-vs-google-apps-script): An Apps Script web app is free and runs custom logic, but supports only GET and POST, does not answer CORS preflight requests, cannot set HTTP status codes, and leaves auth, filtering and caching to your code. SheetDB provides those as settings and endpoints.
- [SheetDB vs Sheety](https://sheetdb.io/compare/sheetdb-vs-sheety): Both are hosted Google Sheets REST APIs. Sheety wraps records in a sheet-named key, camelCases column names, filters by exact value and limits rows per sheet by plan. SheetDB has no per-plan row limit, returns a flat array with original column names, supports operator and OR search, sorting, configurable caching, batch updates, CORS and IP restrictions, a WordPress plugin and an HTML snippet.
- [All comparisons](https://sheetdb.io/compare).