❗Try our Datasets API – We encourage you to try our Datasets API for the most simple, powerful way to access your most important data with Geckoboard.

This article outlines how to get data from an external API into Geckoboard. You might choose this method of getting data into Geckoboard when the integration you would like is not already available, such as from your company’s own API.

There are, however, other ways to get data into Geckoboard that are worth trying before using our Custom Widgets.

Before you start

You can choose the data that you want to see on your dashboard and decide how you would like it visualized.
Understand how to get that data from the data source. For example, which endpoints do you need, and how is authentication handled?
Decide which method (Push or Poll) is best based on your development environment, application design, and data source.
Design how the data that you get back from the data source should be transformed into the widget’s data.

Creating Custom Widgets using Node.js

Node.js is an open-source server framework and a helpful tool for getting data from a data source into your Custom Widgets on your Geckoboard dashboard. Please read our guide to creating Custom Widgets using Node.js.

Further reading

The process explained

This diagram explains the flow of data from its source to your dashboard.

Data source

The data you would like to see on your dashboard. This can be your own systems and databases or a third-party/external API.

Your App

To use Custom Widgets, you need to develop an app that requests the data from the data source, transforms it to meet the format Geckoboard expects, and then sends it to Geckoboard.

Output

Your application needs to format the data from the data source into the format the widget expects. Each widget type has a format defined in the Developer Documentation.

Your Dashboard

Your app then either sends the data directly to Geckoboard or responds to a request from Geckoboard for the data you want in the widget.

Push vs. Poll

There are two ways Custom Widgets can receive data: Push and Poll methods.

The Push method means that your app sends the data directly to Geckoboard’s API. You are given a URL to send your widget data to.

The Poll method means that Geckoboard will send a request to the link you give it and expects your app to respond with the data for the widget.

Tip: The most significant advantage of the Push method is that you can send data whenever you’re ready. For example, if you need to perform a long-running task to get your data ready, using the Push method is best so that Geckoboard doesn’t time out waiting for the data (with the Poll method).

Create a new Custom Widget Poll widget

To create a Poll Custom Widget, follow these steps:

Hover your cursor over an empty space on your dashboard and click the + button. Alternatively, you can just click Add widget, located in the top right of your dashboard.
Search for Custom Widgets using the Search sources field. Alternatively, you can scroll down the alphabetical list of integrations until you reach Custom Widgets.
Click on Custom Widgets LEGACY.
For this example, we'll create a Line Chart. Click on Line Chart to begin setting up your widget.
When the poll method is selected Geckoboard will periodically send a request to the endpoints specified on the widget. It expects to receive a response with a valid payload from your application.

To do this, you'll need to copy the JSON payload from our Custom Widgets documentation and host it on Github as a gist. The code is:
```
{
  "y_axis": {
    "format": "currency",
    "unit": "USD"
  },
  "series": [
    {
      "name": "GBP -> USD",
      "data": [
        1.62529,
        1.56991,
        1.50420,
        1.52265,
        1.55356,
        1.51930,
        1.52148,
        1.51173,
        1.55170,
        1.61966,
        1.59255,
        1.63762
      ]
    }
  ]
}
```
You can also use a service like Dropbox to host your data or your own website. The widget just needs to access a link that hosts a file with data feed.
Once you've saved the Gist, you'll now want a URL you can add to the widget that'll take it directly to the data. In Github, Click the Raw button. Now copy the URL in the address bar. This is the link you'll need from the widget to work.
Return to the Line Chart configuration screen in Geckoboard. Paste the URL from in the URL Date Feed field.
Set a Reload Time that makes sense for your widget.
When you've finished configuring your widget, click Add widget.
You'll now be taken back to your dashboard complete with your new widget.

Note: This example of a simple widget will need to be updated manually. To experience the full potential of Custom Widgets it might be necessary for you to create scripts to update the widgets for you programmatically.

Create a new Custom Widget Push widget

To create a Push Custom Widget, follow these steps:

Click Add widget, located in the top right of your dashboard.
Search for Custom Widgets using the Search sources field. Alternatively, you can scroll down the alphabetical list of integrations until you reach Custom Widgets.
Click on Custom Widgets LEGACY.
For this example, we'll create a RAG Column & Numbers widget. Click on RAG Column & Numbers to begin setting up your widget.
Select Push in the Method field. The config window will only show the Push URL and Widget key fields.
Click Add widget. You'll now be taken back to your dashboard, complete with your new widget.
Unlike the poll method, where data has to be exposed for Geckoboard to access it, the push API allows data to be pushed directly into our widgets and sent.

Note: The push API uses JSON exclusively. Additionally, files should be at most 1 MB in size.

In essence, to push data to your widget what you're doing is a post HTTP request with the correct payload to the URL specified in the widget configuration screen. To achieve this, we'll push to a widget via cURL. Our Custom Widgets developer documentation includes an example on how to push data by cURL. This is the example:
```
curl -X POST https://push.geckoboard.com/v1/send/example-widget-key -d '{"api_key":"example-api-key","data":{"item":[{"text":"This is a new message","type":0}]}}' -H "Content-Type:application/json"
```
Hover your mouse pointer over the new widget. Click the more options icon in the top right corner to open the widget options. Click Edit.

Copy the Push URL and replace the URL in the example cURL request.

curl -X POST https://push.geckoboard.com/v1/send/160317-35c2eaa0-52f6-0137-24d8-0eef46684bc6 -d '{"api_key":"example-api-key","data":{"item":[{"text":"This is a new message","type":0}]}}' -H "Content-Type:application/json"

Find your Geckoboard API key and and replace the example-api-key in the example cURL request.

curl -X POST https://push.geckoboard.com/v1/send/160317-35c2eaa0-52f6-0137-24d8-0eef46684bc6 -d '{"api_key":"568vrb67432f8767231c67d21c08e12a","data":{"item":[{"text":"This is a new message","type":0}]}}' -H "Content-Type:application/json"

Now we'll add our payload to the cURL request. As an example, we'll copy the RAG payload from our Custom Widgets documentation.
```
{ "item": [ { "value": 16, "text": "Long past due" }, { "value": 64, "text": "Overdue" }, { "value": 32, "text": "Due" } ] }
```

Then we'll add the payload to the cURL request.

curl -X POST https://push.geckoboard.comv1/send/160317-35c2eaa0-52f6-0137-24d8-0eef46684bc6 -d '{"api_key":"568vrb67432f8767231c67d21c08e12a","data":{ "item": [ { "value": 16, "text": "Long past due" }, { "value": 64, "text": "Overdue" }, { "value": 32, "text": "Due" } ] } }' -H "Content-Type:application/json"

Now copy the request and paste it into your terminal window. If you're using a Windows machine you'll need to escape all the quotes.
If all is correct, you'll receive a reply in your terminal client confirming that the push has been successful.

Note: This example of a simple widget will need to be updated manually. To experience the full potential of Custom Widgets it might be necessary for you to create scripts to update the widgets for you programmatically.

Video resources

Node.js module for Push method widgets

Custom Widgets error: 'widget does not exist'

Custom Widget polling timeout error

How to use the Datasets API

Guide to using Custom Widgets