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, such as with CSV files or a spreadsheet, that are worth trying before using our Custom Widgets.

Before you start

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 a Custom Widgets using Node.js

Node.js is an open-source server framework and a useful tool for getting data from a data source into your Custom Widgets on your Geckoboard dashboard.

Read our guide to creating Custom Widgets using Node.js.

Further reading

The process explained

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

Data source

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

Your App

In order 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 this data 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 that 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 that you give it, and expects your app to respond with the data for the widget.

Tip

The biggest 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 in order 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 click the + button.

Alternatively, click Add widget, located in the top right of your dashboard.
Search for Custom Widgets using the Search sources field.

Alternatively, you can also 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 and it expects to receive a response with a valid payload from your application.

In order 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 be able to access a link that hosts a file with data feed.
Once you've saved the Gist, you'll now want to have 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 programmatically update the widgets for you.

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 also 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 now only show the 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 not exceed 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.

In order 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 bring up 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.com/v1/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 programmatically update the widgets for you.