OpenSheet - Google Sheets to RESTful JSON API Documentation

OpenSheet is an elegant and lightweight service that instantly turns any Google Spreadsheet into a clean RESTful JSON API. No Google Cloud Platform project setup, no API keys, and no backend database required. Simply set your sheet to public view-only, and start consuming data instantly!

---

API URL Structure & Specification

OpenSheet implements a clear RESTful routing format:

GET https://gh-proxy.org/opensheet/{spreadsheet_id}/{sheet_name_or_index}

• {spreadsheet_id}: The unique ID string extracted from your Google Sheets URL.
• {sheet_name_or_index}: The specific tab name (e.g. list, Sheet1) or the 1-based numerical index (e.g. 1, 2).

---

3-Step Rapid Onboarding

Step 1: Prepare the Header Row

In your Google Sheet, the first row defines the keys of the JSON objects in the response array:

• Ensure every column in row 1 has a descriptive title (e.g. name, amount, date, message).
• Avoid empty cells or duplicate column names in the first row.

Step 2: Set Sheet Sharing to Public

1. Open your target Google Sheet and click the Share button in the upper-right corner.
2. Under General access, change the permission from “Restricted” to “Anyone with the link”.
3. Keep the role as “Viewer”.

Step 3: Extract the Spreadsheet ID & Call the API

Copy the ID between /d/ and /edit from your browser address bar:

https://docs.google.com/spreadsheets/d/1NuaXdRper70yHQXNYZaXR0Jv-1xELZ_RaPuEjWDaZns/edit
                                        └─────────────────┬──────────────────┘
                                                    Spreadsheet ID

---

Live Examples

1. Source Google Spreadsheet

Public demonstration sheet:

https://docs.google.com/spreadsheets/d/1NuaXdRper70yHQXNYZaXR0Jv-1xELZ_RaPuEjWDaZns/edit

2. Corresponding JSON API Requests

• Request by Sheet / Tab Name:

  curl https://gh-proxy.org/opensheet/1NuaXdRper70yHQXNYZaXR0Jv-1xELZ_RaPuEjWDaZns/list
  

• Request by Sheet Index (First Tab):

  curl https://gh-proxy.org/opensheet/1NuaXdRper70yHQXNYZaXR0Jv-1xELZ_RaPuEjWDaZns/1
  

3. Response JSON Structure

[
  {
    "name": "Alice",
    "amount": "$50.00",
    "date": "2026-09-01",
    "message": "Thank you for the open source project!"
  },
  {
    "name": "Bob",
    "amount": "$100.00",
    "date": "2026-09-02",
    "message": "Keep up the great work!"
  }
]

4. Real-World Implementation

Our donor wall page is powered dynamically by OpenSheet:

• URL: https://gh-proxy.org/en/donate-list

---

Advanced Query Parameters

?raw=true Unformatted Raw Values

• Default Behavior: OpenSheet returns the display text as formatted by Google Sheets. For example, a currency value $1,234.56 is returned as a formatted string "$1,234.56".
• With ?raw=true: Returns native JavaScript types (numbers such as 1234.56, booleans true/false), ideal for client-side mathematical computations and data visualization charts.

https://gh-proxy.org/opensheet/1NuaXdRper70yHQXNYZaXR0Jv-1xELZ_RaPuEjWDaZns/list?raw=true

---

10-Minute Global Anycast Edge Caching

Every OpenSheet API endpoint is cached automatically across global Anycast edge nodes:

• Sub-30ms Global Latency: Frequently accessed spreadsheets are served directly from the edge node closest to the client.
• High Concurrency Shield: Traffic spikes are absorbed at the edge layer, protecting your spreadsheet from Google API quotas and rate limits.
• Automated Invalidation: The edge cache automatically re-fetches fresh data from Google every 10 minutes. Changes made in Google Sheets propagate worldwide within 10 minutes.

---

Code Integration Snippets

JavaScript / TypeScript (Fetch API)

async function loadSheetData() {
  const SPREADSHEET_ID = "1NuaXdRper70yHQXNYZaXR0Jv-1xELZ_RaPuEjWDaZns";
  const SHEET_NAME = "list";
  
  const response = await fetch(`https://gh-proxy.org/opensheet/${SPREADSHEET_ID}/${SHEET_NAME}`);
  const data = await response.json();
  console.log("Retrieved sheet records:", data);
  return data;
}

Python (requests)

import requests

url = "https://gh-proxy.org/opensheet/1NuaXdRper70yHQXNYZaXR0Jv-1xELZ_RaPuEjWDaZns/list"
response = requests.get(url)
items = response.json()

for row in items:
    print(row.get("name"), row.get("amount"))