{"id":20047803,"url":"https://github.com/interactivethings/gsheets","last_synced_at":"2025-08-21T02:32:12.755Z","repository":{"id":23497615,"uuid":"26863095","full_name":"interactivethings/gsheets","owner":"interactivethings","description":"Get public Google Sheets as plain JavaScript/JSON","archived":false,"fork":false,"pushed_at":"2021-09-13T15:56:42.000Z","size":270,"stargazers_count":86,"open_issues_count":2,"forks_count":8,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-12-06T15:11:41.816Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interactivethings.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-19T13:41:53.000Z","updated_at":"2023-09-07T06:20:17.000Z","dependencies_parsed_at":"2022-08-25T02:30:51.399Z","dependency_job_id":null,"html_url":"https://github.com/interactivethings/gsheets","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactivethings%2Fgsheets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactivethings%2Fgsheets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactivethings%2Fgsheets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactivethings%2Fgsheets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interactivethings","download_url":"https://codeload.github.com/interactivethings/gsheets/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230479864,"owners_count":18232630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T11:38:32.975Z","updated_at":"2024-12-19T18:18:18.820Z","avatar_url":"https://github.com/interactivethings.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gsheets\n\nGet public Google Sheets as plain JavaScript/JSON.\n\n:point_right: [Try gsheets in your browser](https://runkit.com/npm/gsheets)\n\n## Usage\n\n### Google Sheets Api Key\n\nStarting with version 3.0.0, gsheets uses the official Google Sheets API v4, which requires an API key. To get an API key [follow these instructions](https://developers.google.com/sheets/api/guides/authorizing#APIKey). You also need to enable the [Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com) for the project you've generated the API key for.\n\n### Node.js\n\nNode.js \u003e= 12 is required.\n\n```\nnpm install gsheets\n```\n\n```js\nconst gsheets = require(\"gsheets\");\n\ngsheets\n  .getWorksheet(\"SPREADSHEET_KEY\", \"WORKSHEET_TITLE\", \"GSHEETS_API_KEY\")\n  .then(\n    (res) =\u003e console.log(res),\n    (err) =\u003e console.error(err)\n  );\n```\n\n### In the Command Line\n\n```\ngsheets --key --title [--apiKey] [--out] [--pretty] [--dsv]\n  --key     Spreadsheet Key (ID), required\n  --title   Worksheet title, required\n\n  --apiKey  Google Sheets v4 API key,\n  --out     Output file; defaults to /dev/stdout\n  --dsv     Format as delimiter-separated values\n  --csv     Shortcut for --dsv=,\n  --tsv     Shortcut for --dsv=$'\\t'\n```\n\nSupports providing the apiKey via arg:\n\n```sh\nnpx gsheets --key=SPREADSHEETID --title=foobar --apiKey=GSHEETS_API_KEY --pretty\n```\n\nor via env:\n\n```sh\nnpx GSHEETS_API_KEY=xyz gsheets --key=SPREADSHEETID --title=foobar --pretty\n```\n\nif you are using dotenv in your project, you can specify GSHEETS_API_KEY as a var in your .env file and run:\n\n```sh\nNODE_OPTIONS='-r dotenv/config' gsheets --key=SPREADSHEETID--title=foobar --pretty\n```\n\n## Features\n\n- Plain JS/JSON data. No 'models'. Just use `.map`, `.filter` etc.\n- Correct handling of numeric cells (no formatted strings for numbers!)\n- Empty cells are converted to `null`\n- Empty rows and empty columns are omitted\n- Empty worksheets returns an object with an empty data array: `{data: []}`\n\n## Caveats\n\n- Beware of cells formatted as dates! Their values will be returned as Excel-style [DATEVALUE](http://office.microsoft.com/en-001/excel-help/datevalue-function-HP010062284.aspx) numbers (i.e. based on the number of _days_ since January 1, 1900)\n\n## Why not use another library?\n\nThere are a few libraries around which allow you to access Google Spreadsheets, most notably [Tabletop](https://github.com/jsoma/tabletop). However, they all have one or several drawbacks:\n\n- They wrap the output in classes or models with a custom API, whereas all we really need is an array of JS objects\n- Tabletop just logs errors to the console which makes proper error handling impossible\n- Incorrect handling of numeric cell values (you only get a _formatted_ string instead of the actual number, e.g. `\"123'456.79\"` instead of `123456.789`)\n\n## API\n\n```js\nvar gsheets = require(\"gsheets\");\n```\n\n#### getWorksheet(\u003ci\u003espreadsheetKey\u003c/i\u003e: string, \u003ci\u003eworksheetTitle\u003c/i\u003e: string, , \u003ci\u003egsheetsApiKey\u003c/i\u003e: string): Promise\n\nReturns the contents of a worksheet, specified by its title.\n\nFor empty worksheets `data` is `[]`.\n\n```js\ngsheets\n  .getWorksheet(\"SPREADSHEET_KEY\", \"WORKSHEET_TITLE\", \"GSHEETS_API_KEY\")\n  .then((res) =\u003e console.log(res));\n```\n\nExample Response:\n\n```js\n{\n  \"data\": [\n    {\n      \"foo\": \"bar\",\n      \"baz\": 42,\n      \"boing\": null\n    },\n    // more rows ...\n  ]\n}\n```\n\n## Development\n\nReplace \"YOUR_GSHEETS_API_KEY\" in index.tests.js with your key, then run the tests with:\n\n```sh\nnpm run test:watch\n```\n\nHave a look at the [test spreadsheet](https://docs.google.com/spreadsheets/d/1dmAQO0zCQz5SNUKalw9NNXwTM6TgDBZ820Ftw-cz5gU/edit#gid=257911996)\n\nPublish a new version with\n\n```\nnpm run shipit\n```\n\n## Author\n\nJeremy Stucki, [Interactive Things](http://www.interactivethings.com)\n\n## License\n\nBSD, see LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finteractivethings%2Fgsheets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finteractivethings%2Fgsheets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finteractivethings%2Fgsheets/lists"}