# Google Spreadsheet Scraper API - Spreadsheet to JSON (`vonsensey/google-spreadsheet-scraper-api`) Actor Point it at a Google spreadsheet and get clean JSON rows: every cell keyed by its column header, numbers as numbers, dates ISO-normalised, every tab in one schema. No Google login and nothing to install. Read several spreadsheets in one run, and pay nothing for a run that reads nothing. - **URL**: https://apify.com/vonsensey/google-spreadsheet-scraper-api.md - **Developed by:** [Blackcube](https://apify.com/vonsensey) (community) - **Categories:** Automation, Integrations, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 sheet rows This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Google Spreadsheet Scraper API
Google Sheets Suite  •  5 Actors, one codebase, one row billed once
Google Sheets Scraper API
Sheet to JSON, No OAuth		Google Spreadsheet Scraper API
➤ You are here		Google Sheets to JSON API
Sheet as a JSON Endpoint
Google Sheet Monitor API
Track Row Changes on a Schedule		Private Google Sheets Reader API
Service Account Access
**More from this account:** [YouTube Transcript Suite](https://apify.com/vonsensey/youtube-transcript-scraper) · [Website Contact & Email Suite](https://apify.com/vonsensey/website-contact-email-extractor) · [Career Site & ATS Jobs Suite](https://apify.com/vonsensey/career-page-job-postings-scraper-api) · [Google News Suite](https://apify.com/vonsensey/google-news-scraper-api) · [Keyword Research Suite](https://apify.com/vonsensey/google-keyword-ideas-scraper) · [Shopify Store Intelligence Suite](https://apify.com/vonsensey/shopify-store-leads-scraper) · [eBay Data Suite](https://apify.com/vonsensey/ebay-scraper-api) · [Amazon Reviews Suite](https://apify.com/vonsensey/amazon-reviews-scraper-api) · [Reddit](https://apify.com/vonsensey/reddit-scraper-posts-comments-api) · [Meta Ad Library](https://apify.com/vonsensey/facebook-ads-library-scraper-meta-ad-api) · [Vinted](https://apify.com/vonsensey/vinted-scraper-api) · [Trustpilot Review Intelligence Suite](https://apify.com/vonsensey/trustpilot-reviews-scraper) · [App Store & Google Play Reviews Suite](https://apify.com/vonsensey/app-store-google-play-reviews-scraper) · [Business Reviews Suite](https://apify.com/vonsensey/business-reviews-aggregator-scraper-api) · [Amazon Product Data Suite](https://apify.com/vonsensey/amazon-product-scraper-api) · [TikTok Suite](https://apify.com/vonsensey/tiktok-scraper-api) · [Snapchat Suite](https://apify.com/vonsensey/snapchat-scraper-api) · [LinkedIn Public Data Suite](https://apify.com/vonsensey/linkedin-scraper-api) · [Instagram Suite](https://apify.com/vonsensey/instagram-posts-scraper-api) · [Contact Validation Suite](https://apify.com/vonsensey/email-verifier-validator-api) #### The Google Sheets suite - [Google Sheets Scraper API](https://apify.com/vonsensey/google-sheets-scraper-api) — any sheet as a typed dataset — every tab, SQL-like filters, private sheets, change monitoring - [Google Sheets to JSON API](https://apify.com/vonsensey/google-sheets-to-json-scraper-api) — a sheet as a JSON endpoint, with real types and server-side filtering - [Google Sheet Monitor API](https://apify.com/vonsensey/google-sheet-monitor-change-tracker-scraper-api) — watch a sheet on a schedule and get only what changed - [Private Google Sheets Reader API](https://apify.com/vonsensey/private-google-sheets-reader-scraper-api) — read sheets that are not link-shared, via your own service account Point it at a Google spreadsheet, get clean JSON rows back. No Google account, no OAuth, no add-on to install — a link-shared spreadsheet is readable from its URL alone. ### Quick start 1. Open the sheet → **Share** → **General access** → **Anyone with the link** → **Viewer**. 2. Click **Copy link**. 3. Paste it into the **Sheet URL** input and press **Start**. Every tab of the spreadsheet comes back in one dataset and one schema, each row stamped with the tab it came from. ### What people use it for - Pull a spreadsheet somebody in operations maintains into an automated workflow. - Turn a shared price list, product list or contact list into rows an app can read. - Consolidate several client spreadsheets into one dataset in a single run. - Hand an LLM or an agent clean, typed rows instead of a CSV to parse. ### Input recipes **A whole spreadsheet** ```json { "url": "https://docs.google.com/spreadsheets/d/%3Cid%3E/edit?usp=sharing" } ``` **Named tabs only** ```json { "url": "https://docs.google.com/spreadsheets/d/%3Cid%3E/edit", "tabs": ["Prices", "Stock"] } ``` **Several spreadsheets at once** ```json { "url": "https://docs.google.com/spreadsheets/d/%3Cid-1%3E/edit", "urls": ["https://docs.google.com/spreadsheets/d/%3Cid-2%3E/edit"] } ``` **Rows without a header row** — columns are named with the spreadsheet's own letters ```json { "url": "https://docs.google.com/spreadsheets/d/%3Cid%3E/edit", "headersRow": 0 } ``` ### What a row looks like ```json { "type": "row", "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms", "spreadsheetTitle": "Example Spreadsheet", "sheetName": "Class Data", "gid": 0, "rowNumber": 2, "changeStatus": null, "cells": { "Student Name": "Alexandra", "Gender": "Female", "Class Level": "4. Senior", "Home State": "CA", "Major": "English", "Extracurricular Activity": "Drama Club" }, "scrapedAt": "2026-09-01T00:00:00.000Z" } ``` Every cell is keyed by its column header. With **Typed values** on (the default) numbers arrive as numbers, booleans as booleans and date cells as ISO-8601 strings, so the data is ready for a database load, a JSON pipeline or an LLM prompt without a cleaning pass. Turn it off and every value is exactly the text the sheet displays. Duplicate headers are de-duplicated (`Tags`, `Tags_2`), a headerless sheet names its columns with the sheet's own letters (`A`, `B`, …), and the invisible trailing columns Google pads every sheet with are dropped. Alongside the data rows every run returns free rows you are never billed for: a **coverage** row per sheet (tabs requested, read and errored; rows read, delivered, unchanged and removed; whether the run was complete) and one **summary** row with the exact spend. ### What it costs | You pay for | Price | |---|---| | Each row delivered | **$2.00 per 1,000 rows** | | Each row from a private sheet (service account) | **$10.00 per 1,000 rows** | | Each spreadsheet successfully read | **$0.015** | **Free, always:** a sheet that could not be read, a tab that failed, error rows, coverage rows, removed-row notices, the metadata row, the run summary — and on a monitoring schedule, every row that did not change. A run that reads nothing costs nothing. Set **Cost ceiling (USD)** to stop any run before it passes a number you choose; the free summary row reports what the run actually spent. ### Use it from n8n, MCP, the API or a schedule Built to be called by a workflow, not only from the Store form. The Actor is `vonsensey/google-spreadsheet-scraper-api`; every snippet below sends `{}`, which runs the defaults shown on the form — replace it with your own input. #### n8n Install the **Apify** community node (`@apify/n8n-nodes-apify` under *Settings → Community Nodes*, or search "Apify" on n8n Cloud). Add **Apify → Run Actor** with Actor `vonsensey/google-spreadsheet-scraper-api` and your input JSON, then **Apify → Get Dataset Items** on the run's `defaultDatasetId` and pipe the rows anywhere. For scheduled runs, the **On new Apify Event** trigger fires when a run of this Actor finishes. #### MCP (Claude, Cursor, VS Code, any MCP client) ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com/?tools=vonsensey/google-spreadsheet-scraper-api", "headers": { "Authorization": "Bearer " } } } } ``` Your agent then calls `vonsensey/google-spreadsheet-scraper-api` as a tool with the same input the form takes and reads the dataset back. #### REST API (one call, rows in the response) ```bash curl -X POST "https://api.apify.com/v2/acts/vonsensey~google-spreadsheet-scraper-api/run-sync-get-dataset-items?token=$APIFY_TOKEN" \ -H "Content-Type: application/json" -d '{}' ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient("") run = client.actor("vonsensey/google-spreadsheet-scraper-api").call(run_input={}) for row in client.dataset(run["defaultDatasetId"]).iterate_items(): print(row) ``` #### JavaScript ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('vonsensey/google-spreadsheet-scraper-api').call({}); const { items } = await client.dataset(run.defaultDatasetId).listItems(); ``` #### Make, Zapier, LangChain, CrewAI The Apify app in **Make** and **Zapier** has a *Run an Actor* module: pick `vonsensey/google-spreadsheet-scraper-api`. In **LangChain** and **CrewAI** the Apify tool wrappers take the same Actor id. A daily **schedule** needs nothing but the Console: *Schedules → Create → this Actor → cron*, and the dataset fills on its own. ### Use cases - **Feed a pipeline from a spreadsheet.** Keyword lists, URL lists, ASINs, account lists — the team maintains them in Sheets, and this turns that sheet into typed input for the rest of the run. - **Sheets as an API.** Point an app or an agent at a dataset that is always the current contents of a spreadsheet somebody in operations keeps up to date — numbers as numbers, booleans as booleans, dates as ISO-8601, every cell keyed by its column header. - **Watch a living sheet.** Put it on a schedule with `monitor` on and get a change feed: every row stamped `added`, `updated`, `removed` or `unchanged` against the previous run. - **Consolidate client sheets.** Twelve customers each with their own spreadsheet, one run, one schema, and every row stamped with the spreadsheet id, tab name and gid it came from. - **Read the sheets that are not link-shared.** Internal sheets, client data and finance tabs come through your own Google service account — share the sheet with its address once, paste the JSON key, and you get the same typed rows and the same monitoring. ### Run it on a schedule A one-off pull answers a question; a schedule answers it every day without you. Open **Schedules** in the Apify Console, point a cron at this Actor, and the dataset keeps filling on its own — no server, no cron box, no babysitting. Everything here is built to be re-run: you are billed per row delivered, and the FAQ below says exactly what a scheduled run that finds nothing new costs. ### FAQ #### Do I need a Google account, OAuth or a Drive prompt? No. A link-shared sheet is read from its URL alone — no sign-in, no OAuth screen, no Drive authorization. A sheet that is not link-shared needs your own service-account key, which you paste into the run as a secret input. #### My run said the sheet is not link-shared. What now? Copying a share link does not share the sheet. While sharing is **Restricted**, Google answers every public request with a sign-in page. Fix it with **Share → General access → Anyone with the link → Viewer**, or use the service-account route instead. There is no third option — Google enforces this. #### Can I filter before I pay for rows? Yes. Put a SQL-like statement in `query` — `select A, C where C contains 'traffic' order by A limit 50` — and Google applies it before anything is sent, so filtered-out rows are never delivered and never billed. Column letters are the sheet's own. In query mode `rowNumber` comes back `null`, because a filtered result's true position in the sheet is unknowable and this Actor returns null rather than inventing a number. #### Will a schedule re-charge me for data I already have? No. With `monitor` on, only rows that are new or whose cells actually changed are billed; `unchanged` and `removed` rows are delivered free. A quiet sheet still costs its one **sheet sync** — that is the charge for the sheet being watched, and it is what keeps an hourly cron affordable rather than free. #### Can I read every tab, and several spreadsheets, in one run? Yes to both. Leave **Tabs** empty and every tab comes back in one schema, each row carrying its `sheetName` and `gid`; name tabs or gid numbers to narrow it. Put extra spreadsheets in `urls` and one run covers all of them — one sheet reached twice in the same run is still one sync. #### Do I need a proxy? No. Everything is handled for you and there is nothing to buy on top. *** Something wrong, or a field you need that is missing? Open an issue on the **Issues** tab — it is read and it gets fixed. If this saved you time, a rating on the Store page helps the next person find it. # Actor input Schema ## `url` (type: `string`): The sheet's share link — copy it from Share → Copy link while the sheet is shared as 'Anyone with the link → Viewer'. Also accepted: the export/gviz/published-to-web CSV URL, the htmlview link, or the bare spreadsheet ID. No Google sign-in, no OAuth screen and no Drive permission prompt. ## `urls` (type: `array`): Optional. Extra sheets to read in the SAME run — paste one share link per line. Every row is stamped with the spreadsheet it came from, so twelve client sheets come back in one dataset and one schema. The row budget is split across the sheets so the first one cannot eat it. ## `spreadsheetId` (type: `string`): Optional. The long ID from the sheet URL, used directly instead of parsing the URL. It replaces the Sheet URL above when both are set; any entries in More sheet URLs are still read as well. ## `tabs` (type: `array`): Optional. Sheet tab names or gid numbers to read, e.g. `Leads` or `0`. Leave empty to read every tab — all tabs come back in one run and one schema, with the tab name on every row. ## `query` (type: `string`): Optional. Google's visualization query language, executed by Google before any rows are returned: `select A, B where C > 100 order by B desc limit 50`. Column letters refer to the sheet's columns. Link mode only — the Sheets API ignores it. ## `headersRow` (type: `integer`): The row the column names live on. 1 is the sheet's first row. Set 0 when the sheet has no header row and columns will be named A, B, C… like the sheet's own column letters. ## `skipRows` (type: `integer`): Optional. How many rows to drop between the header and the data — for sheets that carry a title or a blank line under the header. Rows skipped here are never billed. ## `typed` (type: `boolean`): On: numbers come back as numbers, booleans as booleans, dates as ISO-8601 strings — ready for JSON pipelines, spreadsheets and LLM prompts. Off: every value is the exact text the sheet displays. ## `trimEmpty` (type: `boolean`): Sheets carry invisible trailing columns and blank rows from edits long deleted. On drops columns that have no header and no data in any row, and rows that are completely empty. ## `includeMetadata` (type: `boolean`): Adds one free row describing what was read: the spreadsheet title, every tab with its gid, and the per-tab row counts. ## `maxItems` (type: `integer`): Hard ceiling on billable rows for the whole run, split evenly across the sheets you gave. Free rows — errors, coverage, removed-row notices, the summary — never count against it. ## `maxCostUsd` (type: `number`): A backstop, not an estimate: the run stops delivering and reports budgetReached once billed rows would cost more than this. The default sits well above a full 1,000-row run at every rate, so the row cap is what normally stops a run — lower it if you want a tighter guard. ## `monitor` (type: `boolean`): Remembers what each sheet looked like last run (key-value store, scoped to this Actor) and stamps every row: added, updated, unchanged, or removed. Pair with a schedule to watch a living sheet — unchanged rows are never billed, so a quiet sheet on an hourly cron costs only its per-sheet sync fee. ## `monitorChangesOnly` (type: `boolean`): When monitoring, emit only added, updated and removed rows — unchanged rows are counted in the free coverage row but not delivered, and are never billed. ## `mode` (type: `string`): Auto picks by what you supplied: a service-account key if present, else an API key, else plain link access. Force one only when Google's endpoints misbehave. ## `googleApiKey` (type: `string`): Optional. A Google Cloud API key with the Sheets API enabled. Gives exact tab names and gids from the official API instead of the public HTML page. The sheet must still be link-shared; a key alone cannot read a Restricted sheet. ## `serviceAccountKey` (type: `string`): Optional. The full JSON key of a Google Cloud service account. Share the sheet with the account's email (Share → add editor-less viewer) and this Actor reads PRIVATE sheets through the official Sheets API — the only way to reach a sheet that is not link-shared. Billed at the private-sheet rate. ## Actor input object example ```json { "url": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit?usp=sharing", "urls": [], "tabs": [], "query": "select A,C where C contains 'Senior' order by A limit 20", "headersRow": 1, "skipRows": 0, "typed": true, "trimEmpty": true, "includeMetadata": false, "maxItems": 1000, "maxCostUsd": 25, "monitor": false, "monitorChangesOnly": true, "mode": "auto" } ``` # Actor output Schema ## `dataset` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "url": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit?usp=sharing", "urls": [], "tabs": [], "headersRow": 1, "skipRows": 0, "typed": true, "trimEmpty": true, "includeMetadata": false, "maxItems": 1000, "maxCostUsd": 25, "monitor": false, "monitorChangesOnly": true, "mode": "auto" }; // Run the Actor and wait for it to finish const run = await client.actor("vonsensey/google-spreadsheet-scraper-api").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "url": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit?usp=sharing", "urls": [], "tabs": [], "headersRow": 1, "skipRows": 0, "typed": True, "trimEmpty": True, "includeMetadata": False, "maxItems": 1000, "maxCostUsd": 25, "monitor": False, "monitorChangesOnly": True, "mode": "auto", } # Run the Actor and wait for it to finish run = client.actor("vonsensey/google-spreadsheet-scraper-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "url": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit?usp=sharing", "urls": [], "tabs": [], "headersRow": 1, "skipRows": 0, "typed": true, "trimEmpty": true, "includeMetadata": false, "maxItems": 1000, "maxCostUsd": 25, "monitor": false, "monitorChangesOnly": true, "mode": "auto" }' | apify call vonsensey/google-spreadsheet-scraper-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,vonsensey/google-spreadsheet-scraper-api" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/ZrE5HhyHr586scTX0/builds/ryaPkEdUAaqTNwQKD/openapi.json