2022-05-20 08:48:21 +00:00
---
2024-05-28 05:20:05 +00:00
title: Google Sheets Data Interchange
sidebar_label: Google Sheets
2023-02-28 11:40:44 +00:00
pagination_prev: demos/local/index
pagination_next: demos/extensions/index
2022-05-20 08:48:21 +00:00
---
2023-04-27 09:12:19 +00:00
import current from '/version.js';
2022-05-20 08:48:21 +00:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-04-27 09:12:19 +00:00
import CodeBlock from '@theme/CodeBlock';
2022-05-20 08:48:21 +00:00
2025-01-06 02:51:20 +00:00
:::info pass
2023-04-18 04:46:43 +00:00
2025-01-06 02:51:20 +00:00
This demo focuses on external data processing.
[The "Google Sheets" extension demo ](/docs/demos/extensions/gsheet ) covers Apps
Script integration and user-defined functions.
2023-04-18 04:46:43 +00:00
:::
2023-09-18 06:44:33 +00:00
[Google Sheets ](https://google.com/sheets/about/ ) is a collaborative spreadsheet
service with powerful external APIs for automation.
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
[SheetJS ](https://sheetjs.com ) is a JavaScript library for reading and writing
data from spreadsheets.
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
This demo uses SheetJS to properly exchange data with spreadsheet files. We'll
explore how to use NodeJS integration libraries and SheetJS in three data flows:
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
- "Importing data": Data in a NUMBERS spreadsheet will be parsed using SheetJS
libraries and written to a Google Sheets Document
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
- "Exporting data": Data in Google Sheets will be pulled into arrays of objects.
A workbook will be assembled and exported to Excel Binary workbooks (XLSB).
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
- "Exporting files": SheetJS libraries will read XLSX files exported by Google
Sheets and generate CSV rows from every worksheet.
2022-05-20 08:48:21 +00:00
2024-04-14 07:40:38 +00:00
:::danger pass
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
It is strongly recommended to create a new Google account for testing.
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
**One small mistake could result in a block or ban from Google services.**
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
:::
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
:::caution pass
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
Google Sheets deprecates APIs quickly and there is no guarantee that the
referenced APIs will be available in the future.
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
:::
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
## Integration Details
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
This demo uses the Sheets v4 and Drive v3 APIs through the official `googleapis`
connector module.
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
:::info Initial Setup
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
There are a number of steps to enable the Google Sheets API and Google Drive API
for an account. The [Complete Example ](#complete-example ) covers the process.
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
:::
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
### Document Duality
Each Google Sheets document is identified with a unique ID. This ID can be found
from the Google Sheets edit URL.
The edit URL starts with `https://docs.google.com/spreadsheets/d/` and includes
`/edit` . The ID is the string of characters between the slashes. For example:
```
https://docs.google.com/spreadsheets/d/a_long_string_of_characters/edit#gid=0
|^^^^^^^^^^^^^^^^^^^^^^^^^^^|--- ID
```
The same ID is used in Google Drive operations.
The following operations are covered in this demo:
| Operation | API |
|:------------------------------|:-------|
| Create Google Sheets Document | Sheets |
| Add and Remove worksheets | Sheets |
| Modify data in worksheets | Sheets |
| Share Sheets with other users | Drive |
| Generate raw file exports | Drive |
2023-09-18 06:44:33 +00:00
### Authentication
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
It is strongly recommended to use a service account for Google API operations.
The ["Service Account Setup" section ](#service-account-setup ) covers how to
create a service account and generate a JSON key file.
2022-05-20 08:48:21 +00:00
2023-11-30 07:10:37 +00:00
The generated JSON key file includes `client_email` and `private_key` fields.
These fields can be used in JWT authentication:
```js title="JWT Authentication using a JSON key file"
2024-06-09 03:40:45 +00:00
import { google } from "googleapis";
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
// adjust the path to the actual key file.
// highlight-next-line
import creds from './sheetjs-test-726272627262.json' assert { type: "json" };
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
/* connect to google services */
const jwt = new google.auth.JWT({
2023-09-18 06:44:33 +00:00
email: creds.client_email,
key: creds.private_key,
scopes: [
2024-06-09 03:40:45 +00:00
'https://www.googleapis.com/auth/spreadsheets', // Google Sheets
2025-05-18 20:09:19 +00:00
'https://www.googleapis.com/auth/drive', // Google Drive
2024-06-09 03:40:45 +00:00
'https://www.googleapis.com/auth/drive.file', // Google Drive
2023-09-18 06:44:33 +00:00
]
});
```
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
### Connecting to Services
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
The `google` named export includes special methods to connect to various APIs.
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
#### Google Sheets
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
```js
const sheets = google.sheets({ version: "v4", auth: jwt });
2023-09-18 06:44:33 +00:00
```
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
`google.sheets` takes an options argument that includes API version number and
authentication details.
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
#### Google Drive
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
```js
const drive = google.drive({ version: "v3", auth: jwt });
2022-05-20 08:48:21 +00:00
```
2024-06-09 03:40:45 +00:00
`google.drive` takes an options argument that includes API version number and
authentication details.
2023-09-18 06:44:33 +00:00
### Array of Arrays
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
["Arrays of Arrays" ](/docs/api/utilities/array#array-of-arrays ) are the main
data format for interchange with Google Sheets. The outer array object includes
row arrays, and each row array includes data.
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
SheetJS provides methods for working with Arrays of Arrays:
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
- `aoa_to_sheet` [^1] creates SheetJS worksheet objects from arrays of arrays
- `sheet_to_json` [^2] can generate arrays of arrays from SheetJS worksheets
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
## Export Document Data
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
The goal is to create an XLSB export from a Google Sheet. Google Sheets does
not natively support the XLSB format. SheetJS fills the gap.
2022-05-20 08:48:21 +00:00
2022-10-10 01:42:23 +00:00
### Convert a Single Sheet
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
`sheets.spreadsheets.values.get` returns data from an existing Google Sheet. The
method expects a range. Passing the sheet name as the title will pull all rows.
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
If successful, the response object will have a `data` property. It will be an
object with a `values` property. The values will be represented as an Array of
Arrays of values. This array of arrays can be converted to a SheetJS sheet:
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
```js
async function gsheet_ws_to_sheetjs_ws(id, sheet_name) {
/* get values */
const res = await sheets.spreadsheets.values.get({
spreadsheetId: id,
range: `'${sheet_name}'`
});
const values = res.data.values;
/* create SheetJS worksheet */
const ws = XLSX.utils.aoa_to_sheet(values);
return ws;
2022-05-20 08:48:21 +00:00
}
```
2022-10-10 01:42:23 +00:00
### Convert a Workbook
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
`sheets.spreadsheets.get` returns metadata about the Google Sheets document. In
the result object, the `data` property is an object which has a `sheets`
property. The value of the `sheets` property is an array of sheet objects.
The SheetJS `book_new` [^3] method creates blank SheetJS workbook objects. The
`book_append_sheet` [^4] method adds SheetJS worksheet objects to the workbook.
By looping across the sheets, the entire workbook can be converted:
2022-05-20 08:48:21 +00:00
```js
2024-06-09 03:40:45 +00:00
async function gsheet_doc_to_sheetjs_wb(doc) {
2022-10-10 01:42:23 +00:00
/* Create a new workbook object */
const wb = XLSX.utils.book_new();
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
/* Get metadata */
const wsheet = await sheets.spreadsheets.get({spreadsheetId: id});
2022-10-10 01:42:23 +00:00
/* Loop across the Document sheets */
2024-06-09 03:40:45 +00:00
for(let sheet of wsheet.data.sheets) {
2022-10-10 01:42:23 +00:00
/* Get the worksheet name */
2024-06-09 03:40:45 +00:00
const name = sheet.properties.title;
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
/* Convert Google Docs sheet to SheetJS worksheet */
const ws = await gsheet_ws_to_sheetjs_ws(id, name);
/* Append worksheet to workbook */
XLSX.utils.book_append_sheet(wb, ws, name);
2022-10-10 01:42:23 +00:00
}
2022-05-20 08:48:21 +00:00
2022-10-10 01:42:23 +00:00
return wb;
2022-05-20 08:48:21 +00:00
}
```
2024-06-09 03:40:45 +00:00
This method returns a SheetJS workbook object that can be exported with the
`writeFile` and `write` methods.[^5]
2022-10-10 01:42:23 +00:00
## Update Document Data
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
The goal is to import data from a NUMBERS file to Google Sheets. Google Sheets
does not natively support the NUMBERS format. SheetJS fills the gap.
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
### Create New Document
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
`sheets.spreadsheets.create` creates a new Google Sheets document. It can accept
a document title. It will generate a new workbook with a blank "Sheet1" sheet.
The response includes the document ID for use in subsequent operations:
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
```js title="Create a new document with blank sheet"
const res = await sheets.spreadsheets.create({
requestBody: {
properties: {
/* Document Title */
title: "SheetJS Test"
}
}
});
const id = res.data.spreadsheetId;
2022-10-10 01:42:23 +00:00
```
2024-06-09 03:40:45 +00:00
:::caution pass
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
When using a service worker, the main account does not have access to the new
document by default. The document has to be shared with the main account using
the Drive API:
```js title="Sharing the generated sheet with the main account"
await drive.permissions.create({
fileId: id, // this ID was returned in the response to the create request
fields: "id",
requestBody: {
type: "user",
role: "writer",
emailAddress: "YOUR_ADDRESS@gmail.com" // main address
}
});
```
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
:::
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
### Delete Non-Initial Sheets
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
Google Sheets does not allow users to delete every worksheet.
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
The recommended approach involves deleting every worksheet after the first.
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
The delete operation requires a unique identifier for a sheet within the Google
Sheets document. These IDs are found in the `sheets.spreadsheets.get` response.
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
The following snippet performs one bulk operation using `batchUpdate` :
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
```js title="Deleting non-initial sheets"
/* get existing sheets */
const wsheet = await sheets.spreadsheets.get({spreadsheetId: id});
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
/* remove all sheets after the first */
if(wsheet.data.sheets.length > 1) await sheets.spreadsheets.batchUpdate({
spreadsheetId: id,
requestBody: { requests: wsheet.data.sheets.slice(1).map(s => ({
deleteSheet: {
sheetId: s.properties.sheetId
}
}))}
});
2022-10-10 01:42:23 +00:00
```
2024-06-09 03:40:45 +00:00
### Rename First Sheet
The first sheet must be renamed so that the append operations do not collide
with the legacy name. Since most SheetJS-supported file formats and most
spreadsheet applications limit worksheet name lengths to 32 characters, it is
safe to set a name that exceeds 33 characters.
The `updateSheetProperties` update method can rename individual sheets:
```js title="Rename legacy first sheet"
/* rename first worksheet to avoid collisions */
await sheets.spreadsheets.batchUpdate({
spreadsheetId: id,
requestBody: { requests: [{
updateSheetProperties: {
fields: "title",
properties: {
sheetId: wsheet.data.sheets[0].properties.sheetId,
// the new title is 34 characters, to be exact
title: "thistitleisatleast33characterslong"
}
}
}]}
});
```
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
### Append Worksheets
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
:::note pass
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
The [`read` and `readFile` methods ](/docs/api/parse-options ) generate SheetJS
workbook objects from existing worksheet files.
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
:::
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
Starting from a SheetJS workbook, the `SheetNames` property[^6] is an array of
worksheet names and the `Sheets` property is an object that maps sheet names to
worksheet objects.
Looping over the worksheet names, there are two steps to appending a sheet:
1) "Append a blank worksheet": The `addSheet` request, submitted through the
`sheets.spreadsheets.batchUpdate` method, accepts a new title and creates a new
worksheet. The new worksheet will be added at the end.
2) "Write data to the new sheet": The SheetJS `sheet_to_json` method with the
option `header: 1` [^7] will generate an array of arrays of data. This structure
is compatible with the `sheets.spreadsheets.values.update` operation.
The following snippet pushes all worksheets from a SheetJS workbook into a
Google Sheets document:
```js title="Push data from a SheetJS workbook to a Google Sheets Document"
/* add sheets from file */
for(let name of wb.SheetNames) {
/* (1) Create a new Google Sheets sheet */
await sheets.spreadsheets.batchUpdate({
spreadsheetId: id,
requestBody: { requests: [
/* add new sheet */
{ addSheet: { properties: { title: name } } },
] }
});
/* (2) Push data */
const aoa = XLSX.utils.sheet_to_json(wb.Sheets[name], {header:1});
await sheets.spreadsheets.values.update({
spreadsheetId: id,
range: `'${name}'!A1` ,
valueInputOption: "USER_ENTERED",
resource: { values: aoa }
});
2022-10-10 01:42:23 +00:00
}
```
2024-06-09 03:40:45 +00:00
### Delete Initial Sheet
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
After adding new worksheets, the final step involves removing the initial sheet.
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
The initial sheet ID can be pulled from the worksheet metadata fetched when the
[non-initial sheets were removed ](#delete-non-initial-sheets ):
2022-10-10 01:42:23 +00:00
2024-06-09 03:40:45 +00:00
```js title="Deleting the Initial sheet"
/* remove first sheet */
await sheets.spreadsheets.batchUpdate({
spreadsheetId: id,
requestBody: { requests: [
/* remove old first sheet */
{ deleteSheet: { sheetId: wsheet.data.sheets[0].properties.sheetId } }
] }
});
2022-10-10 01:42:23 +00:00
```
## Raw File Exports
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
In the web interface, Google Sheets can export documents to `XLSX` or `ODS` .
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
Raw file exports are exposed through the `files.export` method in the Drive API:
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
```js title="Export XLSX workbook"
const drive = google.drive({ version: "v3", auth: jwt });
/* Request XLSX export */
const file = await drive.files.export({
/* XLSX MIME type */
mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
fileId: id
});
```
2024-06-11 07:12:51 +00:00
:::note pass
The `mimeType` property is expected to be one of the supported formats[^8]. When
the demo was last tested, the following workbook conversions were supported:
| Format | MIME Type |
|:-------|:--------------------------------------------------------------------|
| XLSX | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
| ODS | `application/x-vnd.oasis.opendocument.spreadsheet` |
:::
2024-06-09 03:40:45 +00:00
The response object has a `data` field whose value will be a `Blob` object. Data
2024-06-11 07:12:51 +00:00
can be pulled into an `ArrayBuffer` and passed to the SheetJS `read` [^9] method:
2022-05-20 08:48:21 +00:00
```js
2024-06-09 03:40:45 +00:00
/* Obtain ArrayBuffer */
const ab = await file.data.arrayBuffer();
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
/* Parse */
2023-09-18 06:44:33 +00:00
const wb = XLSX.read(buf);
```
2024-06-11 07:12:51 +00:00
:::note pass
The code snippet works for XLSX and ODS. Google Sheets supports other formats
with different integration logic.
**Plaintext**
The following formats are considered "plaintext":
| Format | MIME Type |
|:------------------|:----------------------------|
| CSV (first sheet) | `text/csv` |
| TSV (first sheet) | `text/tab-separated-values` |
For these formats, `file.data` is a JS string that can be parsed directly:
```js
/* Request CSV export */
const file = await drive.files.export({ mimeType: "text/csv", fileId: id });
/* Parse CSV string*/
const wb = XLSX.read(file.data, {type: "string"});
```
**HTML**
Google Sheets has one relevant HTML type:
| Format | MIME Type |
|:------------------|:------------------|
| HTML (all sheets) | `application/zip` |
The HTML export of a Google Sheets worksheet includes a row for the column
labels (`A`, `B` , ...) and a column for the row labels (`1`, `2` , ...).
The complete package is a ZIP file that includes a series of `.html` files.
The files are written in tab order. The name of each file matches the name in
Google Sheets.
This ZIP can be extracted using the embedded CFB library:
```js
import { read, utils, CFB } from 'xlsx';
// -------------------^^^-- `CFB` named import
// ...
/* Parse Google Sheets ZIP file */
const cfb = CFB.read(new Uint8Array(ab), {type: "array"});
/* Create new SheetJS workbook */
const wb = utils.book_new();
/* Scan through each entry in the ZIP */
cfb.FullPaths.forEach((n, i) => {
/* only process HTML files */
if(n.slice(-5) != ".html") return;
/* Extract worksheet name */
const name = n.slice(n.lastIndexOf("/")+1).slice(0,-5);
/* parse HTML */
const htmlwb = read(cfb.FileIndex[i].content);
/* add worksheet to workbook */
utils.book_append_sheet(wb, htmlwb.Sheets.Sheet1, name);
});
```
:::
At this point `wb` is a SheetJS workbook object[^10].
2023-09-18 06:44:33 +00:00
## Complete Example
2023-11-30 07:10:37 +00:00
:::note Tested Deployments
2023-09-18 06:44:33 +00:00
2025-05-18 20:09:19 +00:00
This demo was last tested on 2025-05-14 using `googleapis` version `148.0.0` .
2024-06-09 03:40:45 +00:00
The demo uses Sheets v4 and Drive v3 APIs.
:::
:::caution pass
**The Google Cloud web interface changes frequently!**
The screenshots and detailed descriptions may be out of date. Please report any
issues [to the docs repo ](https://git.sheetjs.com/sheetjs/docs.sheetjs.com/ ) or
reach out to [the SheetJS Discord server ](https://sheetjs.com/chat ).
2023-09-18 06:44:33 +00:00
:::
### Account Setup
0) Create a new Google account or log into an existing account.
:::caution pass
A valid phone number (for SMS verification) may be required.
:::
2024-06-09 03:40:45 +00:00
1) Open https://console.cloud.google.com in a web browser.
If this is the first time accessing Google Cloud resources, a terms of service
modal will be displayed. Review the Google Cloud Platform Terms of Service by
clicking the "Google Cloud Platform Terms of Service" link.
2023-09-18 06:44:33 +00:00
2024-04-14 07:40:38 +00:00
:::danger pass
2023-09-18 06:44:33 +00:00
You must agree to the Google Cloud Platform Terms of Service to use the APIs.
:::
2024-06-09 03:40:45 +00:00
Check the box under "Terms of Service" and click "AGREE AND CONTINUE".
2023-09-18 06:44:33 +00:00
### Project Setup
2024-06-09 03:40:45 +00:00
:::info pass
The goal of this section is to create a new project.
:::
2) Open the Project Selector.
In the top bar, between the "Google Cloud" logo and the search bar, there will
be a selection box. Click the `▼` icon to show the modal.
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00

2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
If the selection box is missing, expand the browser window.
2025-05-18 20:09:19 +00:00
3) Click "New project" in the top right corner of the modal.
2024-06-09 03:40:45 +00:00
4) In the New Project screen, enter "SheetJS Test" in the Project name textbox
2025-05-18 20:09:19 +00:00
and select "No organization" in the Location box. Click "Create".
2024-06-09 03:40:45 +00:00
A notification will confirm that the project was created:

2023-09-18 06:44:33 +00:00
### API Setup
:::info pass
The goal of this section is to enable Google Sheets API and Google Drive API.
:::
2025-05-18 20:09:19 +00:00
5) Click "Select a project" and select "SheetJS Test" from the Recent tab.
2024-06-09 03:40:45 +00:00
2025-05-18 20:09:19 +00:00
6) In the search bar, type "Enabled" and select "Enabled APIs & services".
2024-06-09 03:40:45 +00:00
#### Enable Google Sheets API
2023-09-18 06:44:33 +00:00
2025-05-18 20:09:19 +00:00
7) Near the top of the page, click "+ Enable APIs and services".
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
8) In the search bar near the middle of the page (not the search bar at the top),
type "Sheets" and press < kbd > Enter< / kbd > .
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
In the results page, look for "Google Sheets API". Click the card
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
9) In the Product Details screen, click the blue "ENABLE" button.
2023-09-18 06:44:33 +00:00
2025-05-18 20:09:19 +00:00
10) Click the left arrow (`< - ` ) next to " API / Service Details " .
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
#### Enable Google Drive API
2023-09-18 06:44:33 +00:00
2025-05-18 20:09:19 +00:00
11) Near the top of the page, click "+ Enable APIs and services".
2024-06-09 03:40:45 +00:00
12) In the search bar near the middle of the page (not the search bar at the top),
type "Drive" and press < kbd > Enter< / kbd > .
In the results page, look for "Google Drive API". Click the card
13) In the Product Details screen, click the blue "ENABLE" button.
2023-09-18 06:44:33 +00:00
### Service Account Setup
:::info pass
The goal of this section is to create a service account and generate a JSON key.
:::
2024-06-09 03:40:45 +00:00
14) Go to https://console.cloud.google.com or click the "Google Cloud" image in
the top bar.
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
#### Create Service Account
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
15) Click the Project Selector (`:·` icon) and select "SheetJS Test".
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
16) In the search bar, type "Credentials" and select the "Credentials" item with
2025-05-18 20:09:19 +00:00
subtitle "APIs & Services":
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00

2023-09-18 06:44:33 +00:00
2025-05-18 20:09:19 +00:00
17) Click "+ Create credentials". In the dropdown, select "Service account"
2023-09-18 06:44:33 +00:00
2025-05-18 20:09:19 +00:00
18) Enter "SheetJService" for Service account name. Click "Create and continue".
2023-09-18 06:44:33 +00:00
:::note pass
The Service account ID is generated automatically.
:::
2025-05-18 20:09:19 +00:00
19) In Step 2 "Grant this service account access to project", click Continue.
2023-09-18 06:44:33 +00:00
2025-05-18 20:09:19 +00:00
20) In Step 3 click "Done". You will be taken back to the credentials screen
2023-09-18 06:44:33 +00:00
#### Create JSON Key
2024-06-09 03:40:45 +00:00
21) Look for "SheetJService" in the "Service Accounts" table and click the email
address in the row.
2022-05-20 08:48:21 +00:00
2025-05-18 20:09:19 +00:00
22) Click "Keys" in the horizontal bar near the top of the page.
2022-05-20 08:48:21 +00:00
2025-05-18 20:09:19 +00:00
23) Click "Add key" and select "Create new key" in the dropdown.
2022-05-20 08:48:21 +00:00
2025-05-18 20:09:19 +00:00
24) In the popup, select the "JSON" radio button and click "Create".
2024-06-09 03:40:45 +00:00
The page will download a JSON file. If prompted, allow the download.
2022-05-20 08:48:21 +00:00
2025-05-18 20:09:19 +00:00
25) Click "Close"
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
### Create Document
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
:::info pass
The goal of this section is to create a document from the service account and
share with the main account.
:::
26) Create a `SheetJSGS` folder and initialize:
```bash
mkdir SheetJSGS
cd SheetJSGS
npm init -y
2022-05-20 08:48:21 +00:00
```
2023-09-18 06:44:33 +00:00
27) Copy the JSON file from step 24 into the project folder.
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
28) Install dependencies:
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
< CodeBlock language = "bash" > {`\
2024-06-09 03:40:45 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz googleapis`}
2023-09-18 06:44:33 +00:00
< / CodeBlock >
2024-06-09 03:40:45 +00:00
29) Download [`init.mjs` ](pathname:///gsheet/init.mjs ):
```bash
2025-05-18 20:09:19 +00:00
curl -o init.mjs https://docs.sheetjs.com/gsheet/init.mjs
2024-06-09 03:40:45 +00:00
```
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
Edit the marked lines near the top of the file:
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
```js title="init.mjs (edit highlighted lines)"
/* Change this import statement to point to the credentials JSON file */
2023-09-18 06:44:33 +00:00
// highlight-next-line
import creds from './sheetjs-test-726272627262.json' assert { type: "json" };
2024-06-09 03:40:45 +00:00
/* Change this to the primary account address, NOT THE SERVICE ACCOUNT */
2023-09-18 06:44:33 +00:00
// highlight-next-line
2024-06-09 03:40:45 +00:00
const acct = "YOUR_ADDRESS@gmail.com";
2023-09-18 06:44:33 +00:00
```
- `'./sheetjs-test-726272627262.json'` should be replaced with the name of the
JSON file in step 27. The `./` prefix is required!
- `'YOUR_ADDRESS@gmail.com'` should be replaced with the Google Account email
address from step 0.
30) Run the script:
```bash
node init.mjs
```
2024-06-09 03:40:45 +00:00
The script will print three lines:
```
Created Google Workbook a-long-string-of-characters
Created Google Worksheets "SheetJS1" and "SheetJS2"
Shared a-long-string-of-characters with YOUR_ACCOUNT@gmail.com
```
The long string of characters after "Created Google Workbook" is the ID. Take
note of this ID.
2025-05-18 20:09:19 +00:00
31) Sign into Google Drive and select "Shared with me" from the left sidebar. A
shared document "SheetJS Test" should be displayed in the table. It will be
owned by the service account.
2023-09-18 06:44:33 +00:00
2025-05-18 20:09:19 +00:00
32) Click `⋮` next to "SheetJS Test" and select "Open with" > "Google Sheets".
Confirm that the document has two worksheets named "SheetJS1" and "SheetJS2".
2024-06-09 03:40:45 +00:00
Confirm the worksheet data matches the following screenshots:
< table >
<!-- Note: MDX v2 requires the janky indentation -->
< thead > < tr > < th > Sheet< / th > < th > Data< / th > < th > Screenshot< / th > < / tr > < / thead >
< tbody >
< tr >
< td > SheetJS1< / td >
< td >
```js
[
[ "Sheet", "JS" ],
[ 72, 62 ]
]
```
< / td > < td >

< / td >
< / tr >
< tr >
< td > SheetJS2< / td >
< td >
```js
[
[ "Area Code", "Part 1", "Part 2" ],
[ 201, 867, 5309 ],
[ 281, 330, 8004 ]
]
```
< / td > < td >

< / td > < / tr > < / tbody > < / table >
2023-09-18 06:44:33 +00:00
33) Copy the URL and extract the document ID.
The URL of the document will look like
```
https://docs.google.com/spreadsheets/d/a_long_string_of_characters/edit#gid=0
---------------------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^--- ID
```
The ID is a long string of letters and numbers and underscore characters (`_`)
just before the `/edit` part of the URL.
2024-06-09 03:40:45 +00:00
Confirm that this ID matches the ID printed in step 30.
2023-09-18 06:44:33 +00:00
### Load Data from NUMBERS
:::info pass
The goal of this section is to update the new document with data from a sample
NUMBERS file.
:::
2022-05-20 08:48:21 +00:00
2024-04-26 04:16:13 +00:00
34) Download the [test file `pres.numbers` ](https://docs.sheetjs.com/pres.numbers ):
2022-05-20 08:48:21 +00:00
2023-09-18 06:44:33 +00:00
```bash
2025-05-18 20:09:19 +00:00
curl -o pres.numbers https://docs.sheetjs.com/pres.numbers
2023-09-18 06:44:33 +00:00
```
2024-06-09 03:40:45 +00:00
35) Download [`load.mjs` ](pathname:///gsheet/load.mjs ):
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
```bash
2025-05-18 20:09:19 +00:00
curl -o load.mjs https://docs.sheetjs.com/gsheet/load.mjs
2024-06-09 03:40:45 +00:00
```
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
Edit the marked lines near the top of the file:
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
```js title="load.mjs (edit highlighted lines)"
/* Change this import statement to point to the credentials JSON file */
2023-09-18 06:44:33 +00:00
import creds from './sheetjs-test-726272627262.json' assert { type: "json" };
2022-05-20 08:48:21 +00:00
2024-06-09 03:40:45 +00:00
/* Change this to the spreadsheet ID */
const id = "SOME-SPREADSHEETJS-ID";
2022-05-20 08:48:21 +00:00
```
2023-09-18 06:44:33 +00:00
- `'./sheetjs-test-726272627262.json'` should be replaced with the name of the
JSON file in step 27. The `./` prefix is required!
2024-06-09 03:40:45 +00:00
- `"SOME-SPREADSHEETJS-ID"` should be replaced with the Document ID from step 33.
2023-09-18 06:44:33 +00:00
36) Run the script:
```bash
node load.mjs
```
2024-06-09 03:40:45 +00:00
37) Sign into Google Sheets and open the "SheetJS Test" shared document. It
2023-09-18 06:44:33 +00:00
should show a list of Presidents, matching the contents of the test file.
### Export Data to XLSB
:::info pass
The goal of this section is to export the raw data from Google Sheets to XLSB.
:::
2024-06-09 03:40:45 +00:00
38) Download [`dump.mjs` ](pathname:///gsheet/dump.mjs ):
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
```bash
2025-05-18 20:09:19 +00:00
curl -o dump.mjs https://docs.sheetjs.com/gsheet/dump.mjs
2024-06-09 03:40:45 +00:00
```
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
Edit the marked lines near the top of the file:
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
```js title="dump.mjs (edit highlighted lines)"
/* Change this import statement to point to the credentials JSON file */
2023-09-18 06:44:33 +00:00
import creds from './sheetjs-test-726272627262.json' assert { type: "json" };
2024-06-09 03:40:45 +00:00
/* Change this to the spreadsheet ID */
const id = "SOME-SPREADSHEETJS-ID";
2023-09-18 06:44:33 +00:00
```
- `'./sheetjs-test-726272627262.json'` should be replaced with the name of the
JSON file in step 27. The `./` prefix is required!
2024-06-09 03:40:45 +00:00
- `"SOME-SPREADSHEETJS-ID"` should be replaced with the Document ID from step 33.
2023-09-18 06:44:33 +00:00
39) Run the script:
```bash
2023-09-19 19:08:29 +00:00
node dump.mjs
2023-09-18 06:44:33 +00:00
```
2024-06-09 03:40:45 +00:00
The script should create a file `SheetJSExport.xlsb` in the project folder. This
file can be opened in Excel.
2023-09-18 06:44:33 +00:00
### Export Raw Files
:::info pass
The goal of this section is to parse the Google Sheets XLSX export and generate
CSV files for each worksheet.
:::
2024-06-09 03:40:45 +00:00
40) Sign into Google Sheets and open the "SheetJS Test" shared document.
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
41) Click the Plus (`+`) icon in the lower left corner to create a new worksheet.
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
42) In the new worksheet, set cell A1 to the formula `=SEQUENCE(3,5)` . This will
2023-09-18 06:44:33 +00:00
assign a grid of values
2024-06-09 03:40:45 +00:00
43) Download [`raw.mjs` ](pathname:///gsheet/raw.mjs ):
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
```bash
2025-05-18 20:09:19 +00:00
curl -o raw.mjs https://docs.sheetjs.com/gsheet/raw.mjs
2024-06-09 03:40:45 +00:00
```
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
Edit the marked lines near the top of the file:
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
```js title="raw.mjs (edit highlighted lines)"
/* Change this import statement to point to the credentials JSON file */
2023-09-18 06:44:33 +00:00
import creds from './sheetjs-test-726272627262.json' assert { type: "json" };
2024-06-09 03:40:45 +00:00
/* Change this to the spreadsheet ID */
const id = "SOME-SPREADSHEETJS-ID";
2023-09-18 06:44:33 +00:00
```
- `'./sheetjs-test-726272627262.json'` should be replaced with the name of the
JSON file in step 27. The `./` prefix is required!
2024-06-09 03:40:45 +00:00
- `"SOME-SPREADSHEETJS-ID"` should be replaced with the Document ID from step 33.
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
44) Run the script:
2023-09-18 06:44:33 +00:00
```bash
node raw.mjs
```
2024-06-09 03:40:45 +00:00
The script will display the sheet names and CSV rows from both worksheets:
```
#### Sheet1
Name,Index
Bill Clinton,42
GeorgeW Bush,43
Barack Obama,44
Donald Trump,45
Joseph Biden,46
#### Sheet14
1,2,3,4,5
6,7,8,9,10
11,12,13,14,15
```
2023-09-18 06:44:33 +00:00
2024-06-09 03:40:45 +00:00
[^1]: See [`aoa_to_sheet` in "Utilities" ](/docs/api/utilities/array#array-of-arrays-input )
[^2]: See [`sheet_to_json` in "Utilities" ](/docs/api/utilities/array#array-output )
[^3]: See [`book_new` in "Utilities" ](/docs/api/utilities/wb )
[^4]: See [`book_append_sheet` in "Utilities" ](/docs/api/utilities/wb )
[^5]: See [`writeFile` in "Writing Files" ](/docs/api/write-options )
[^6]: See ["Workbook Object" ](/docs/csf/book ) for more details.
[^7]: See [`sheet_to_json` in "Utilities" ](/docs/api/utilities/array#array-output )
2024-06-11 07:12:51 +00:00
[^8]: See ["Export MIME types for Google Workspace documents" ](https://developers.google.com/drive/api/guides/ref-export-formats ) in the Google Developer documentation for the complete list of supported file types.
[^9]: See [`read` in "Reading Files" ](/docs/api/parse-options )
[^10]: See ["Workbook Object" ](/docs/csf/book ) for a description of the workbook object or ["API Reference" ](/docs/api ) for various methods to work with workbook and sheet objects.