Equeum
Search…
⌃K

Adding External Data

You can create resources from external data via our API

What are External Data Resources?

External data can come from any source of information outside the Equeum ecosystem. An external data resource in Equeum is a time series containing data from an external data source. You, the developer, define the resource in Equeum, gather data or write a model in whatever language you prefer, and add data points to the Equeum resource via POST requests.
To add an external data resource to the platform, click the Add button in Library header and follow the on-screen instructions.
This process creates an address and an API token for posting data to the newly created resource, which will now appear in the Library. If you decide to share the resource, you will be responsible for maintaining it.

Implementation details

Data is added to the resource by sending individual values to an Equeum-supplied HTTP endpoint using POST requests.
The body of the POST is a comma-separated pair of a UTC timestamp (adhering to ISO 8601 format) and a numerical value. Data is displayed on the platform in the EST/EDT time zone.
To ensure data integrity, the timestamp must be within one minute of current time when received by the gateway. There is currently no way to submit or correct data for past minutes. Values for missing minutes will be equal to the value of the latest prior-submitted value.
An API token is required to validate submissions to the gateway. API tokens are found in Settings > API Tokens. Sample Python code for submitting values to the gateway is below. Any language or method can be used to submit POST requests.

Data source

The data to be added to an external data resource is obtained by any means you determine. That may, for example, come from a data-provider's API or from a model created by you. We will use data here from the Crypto Fear and Greed Index, using the API endpoint https://api.alternative.me/fng/.

Step 1. Create an external data resource in Equeum

Start by logging in to your Equeum account. In the Library section, click on the Add button in the header above the Resource Library. The Add External Resource popup displays. Enter a name and description and Save.
Note that the Share Now checkbox is enabled. Since we want to share it publicly, enabling it before clicking Save automatically shares the resource.
After clicking Save, this modal displays.
This script is written in Python, but we only need to extract the value of url as this is the link to which we will send POST requests:
https://api.equeum.com/v1/resources/fear_and_greed_index/data?token=<token>
Note that your token value will be different.

Step 2. Find data provider to export your data source

This public API returns daily values for Fear and Greed Index that we need:
https://api.alternative.me/fng/
If you make a GET request, you receive a response with this format:
{
"name": "Fear and Greed Index",
"data": [
{
"value": "18",
"value_classification": "Extreme Fear",
"timestamp": "1657152000",
"time_until_update": "80752"
}
],
"metadata": {
"error": null
}
}

Sample Google Apps Script code

Google Apps is a Rapid-Application-Development (RAD) platform for building applications that can be integrated with other Google products.
Google Apps allows you to write scripts and programs in JavaScript.

Benefits of using Google Apps Script

  1. 1.
    Free with a Google account
  2. 2.
    Easy setup
  3. 3.
    Integrates with other Google Apps - like Google Sheets.
  4. 4.
    Can be scheduled to run at a fixed interval - no need to set up a cron job
  5. 5.
    If a scheduled execution fails, a notification can be sent to your email
  6. 6.
    A cost-effective way to write a script as it runs in the cloud for free
This approach can benefit Equeum users learning how external data resources work.

Write the Google Apps Script

Visit the site: https://www.google.com/script/start/ and login using your Google credentials. Create a new project. For this example, name it Equeum External Resource:
Be sure to save the project periodically by clicking on the disk icon. We create a function to obtain a value from the fear-and-greed index:
function getFearAndGreedIndex() {
var response = UrlFetchApp.fetch('https://api.alternative.me/fng/')
apiResponse = JSON.parse(response);
return apiResponse.data[0].value;
}
We can add a logging line and run the function, by selecting the function name on the function dropdown and clicking on the Run button, to confirm that the request is working:
Now we create a function to create our payload and add it to our external data resource using the Equeum API endpoint:
function sendToExternalResource() {
const now = new Date();
const url = "https://api.equeum.com/v1/resources/fear_and_greed_index/data?token=<token>"
const formattedDate = Utilities.formatDate(now, "Etc/UTC", 'yyyy-MM-dd\'T\'HH:mm:ss\'Z\'');
var options = {
'method' : 'post',
'payload' : formattedDate + "," + getFearAndGreedIndex(),
'headers' : {
'content-type' : 'text/plain'
}
}
UrlFetchApp.fetch(url, options);
}
Save the project, select the new function on the dropdown, and run it. The execution log will confirm that the execution completed. To confirm, let us execute the data source in Equeum. It should look something like this:
As a final step, let’s add a scheduler to keep our script running at an interval. To do this, click on the clock icon on the sidebar:
Next, click the Add Trigger button and populate the form:
This example sets the trigger to run every minute, which is more often than needed for the fear-and-greed data. Click Save, and you are done.

Sample Python code

The following code is used to submit one value to the Equeum API. The value is obtained from the fear-and-greed index, but since the fear-and-greed values vary between 0 and 100 and Equeum functions often work with data that varies between -100 and 100, we will multiply the raw values by 2 and subtract 100 to get values in the range [-100, 100]:
import requests
import json
def fearAndGreedValue():
res = requests.get('https://api.alternative.me/fng/')
j = json.loads(res.text)
return 2 * int(j['data'][0]['value']) - 100
This function submits a value to the Equeum endpoint to be added to the external data resource:
import requests
import datetime
def submitValue(rname, token, value):
ts = datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ')
url = "https://api.equeum.com/v1/resources/" + rname + "/data?token=" + token
body = ts + "," + str(value)
res = requests.post(url, data=body, headers={"content-type": "text/plain"})
rname, is the name you assigned when creating the external data resource. The token is your API token. Test locally to confirm that you’re receiving data and outputting it in the correct format before you submit it to Equeum. value is obtained from the fearAndGreedValue() function.
The function should be called whenever a new datapoint is available. This can be as frequently as once a minute. The fear-and-greed index we are using is only updated daily. As noted, missing values are copied from preceding values, but there is no harm in submitting repeat values when the value has not changed.
Typically new values are submitted by using a timer or scheduler in your program, or by using a cron job to call a process that submits a single value. The following example uses the schedule module to run a task every hour to call submitValue():
import schedule
import datetime
import time
def runme():
submitValue(myResource, myToken, fearAndGreedValue())
schedule.every().hour.do(runme)
while True:
schedule.run_pending()
time.sleep(1)
We assume here thatmyResource and myToken are set to the user’s resource name and API token, respectively.