You can write import scripts using either Javascript or Python to build custom integrations with Equals, pulling in data from outside sources such as third party APIs.

Creating import scripts

To create an import script, first open a new workbook and click on the Connections button in the upper right corner. Then, select Import Script as the datasource.

By default, Equals will load an example import script that will bring dummy data into your workbook. You can toggle between Javascript and Python on this screen.

You can replace the demo data with your custom code. If you have an API key that you don't want to expose in your workbook's script, you can use secret groups to hide these sensitive fields.

Writing import scripts

We currently have two different languages that can be used to build Import Scripts: Javascript (Node 16) and Python (3.9) - you can swap between these for each connected sheet.

Javascript

Usage

First, import the equals library via a require statement

const equals = require("equals");. Then add data and set headings with the below methods.

equals.addRows(data)

Add rows of data to the sheet. Data must be an array of arrays, or an array of objects. Can be called repeatedly to add more data. If you set headers (below) and call addRows with an array of objects, we will use the header values to pluck corresponding values from the objects.

equals.addRow(data)

Add a single row of data (a list or an object).

equals.addHeaders(headers)

Add headings to the data being imported into the sheet. Should be an array of string objects. If not called, then either the keys of the first object, or the values of the first array will be used as headings.

equals.getSecret(secretKeyName)

Retrieve a secret passed to your script from your defined secret groups.

Python

Usage

First, import the equals library with import equals. And then use the following methods to add data to your sheet.

equals.add_rows(data)

Add rows of data to the sheet. Data must be a list of lists, or a list of dicts; such as from JSON. Can be called repeatedly to add more data. If you set headers (below) and call addRows with a list of dicts, we will use the header values to pluck corresponding values from the dicts.

equals.add_row(data)

Convenience method for a single row of data (a list or a dict).

equals.add_headers(headers)

Add headings to the data being imported into the sheet. Should be a list of string objects. If not called, then either the keys of the first dict, or the values of the first list will be used as headings.

equals.get_secret(secret_key_name)

Retrieve a secret passed to your script from your defined secret groups.

Example - retrieving lead data from Intercom with Javascript

We'd like to get a list of all our leads in Intercom. We can do this with some custom Javascript. After adding a secret group with the API key we need, we can use the secret in the script:

const equals = require("equals");  
const axios = require("axios");  
const luxon = require("luxon");  

const apiKey = equals.getSecret("intercom\_api\_key");  
const role = "lead";  

function unixToDateTime(unixTimestamp) {  
  return luxon.DateTime.fromSeconds(unixTimestamp).toFormat('yyyy-LL-dd HH:mm:ss');  
}  

let response = await axios.post("<https://api.intercom.io/contacts/search">,  
  {  
    query: {  
      field: "role",  
      operator: "=",  
      value: role  
    },  
    pagination: { per\_page: 150 },  
    sort: { field: "created\_at", order: "descending" }  
  },  
  {  
    headers: {  
      Authorization: \`Bearer ${apiKey}\`,  
      Accept: "application/json"  
    }  
  });  

equals.addHeaders(\["name", "email", "created\_at"\]);  
response.data\["data"\].forEach((row) => {  
  row\["created\_at"\] = unixToDateTime(row\["created\_at"\]);  
  equals.addRow(row);  
});

Example - fetching stock price with Python

We'd like to be able to pull in stock price information for AAPL on a monthly basis. To do this we can fetch the information from a remote API, and then get it automatically inserted into the spreadsheet.

import equals  
import requests  
import os  

api\_key = equals.get\_secret("alphavantage\_api\_key")  
query = f"<https://www.alphavantage.co/query?function=TIME\_SERIES\_MONTHLY&symbol=AAPL&outputsize=compact&apikey={api\_key}">  

r = requests.get(query)  
data = r.json()  

equals.add\_headers(\["End of month", "Open", "Close"\])  

for eom, datapoint in data\["Monthly Time Series"\].items():  
  equals.add\_row(\[eom, datapoint\["1. open"\], datapoint\["4. close"\]\])

This is enough to get us up and running with Python. Here is the result, with a calculated column giving us the change month by month:

Dependencies

We provide some common dependencies for usage in Import Scripts.

Javascript Version

Node 16.

Javascript Dependencies

The following dependencies are available for usage in Javascript:

Python Version

Python 3.9.

Python Dependencies

The following dependencies are available for usage in Python: