sheet-to-json

A lightweight HTTP API that converts public Google Sheets into JSON or raw CSV.

Usage

Get JSON

GET /json/:sheetId
GET /json/:sheetId?gid=123456789

Returns a JSON object with link (a link back to the source sheet) and data (an array of objects keyed by column headers).

curl https://sheet-json.val.run/json/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms

{
  "link": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit?gid=0",
  "data": [
    { "name": "Alice", "age": "30" },
    { "name": "Bob", "age": "25" }
  ]
}

Get raw CSV

GET /csv/:sheetId
GET /csv/:sheetId?gid=123456789

Returns the raw CSV text exported from Google Sheets.

curl https://sheet-json.val.run/csv/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms

Parameters

:sheetId — The Google Sheet ID from the URL (e.g., 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms)
gid (optional) — The tab/sheet ID. Defaults to 0 (first tab). Find this in the sheet URL after #gid=.

Requirements

The Google Sheet must be publicly accessible ("Anyone with the link" sharing).
Private sheets will return an error.

Endpoints

Route	Description
`GET /`	Health check — returns `{ "ok": true }`
`GET /json/:sheetId`	Fetch sheet as parsed JSON
`GET /csv/:sheetId`	Fetch sheet as raw CSV text
`GET /source`	Redirect to val source code

Architecture

Rendering mermaid diagram...

nbbaier

sheet-exporter