While the Custom Widgets legacy API remains available, updates are no longer provided. If you're trying to bring custom data into your dashboard, we strongly recommend using the Datasets API or another option in this guide instead.
The legacy Custom Widgets API lets you get data from an external API into Geckoboard when the integration you need isn't already available, such as from your company's own internal API. Data is sent to Custom Widgets in either JSON or XML format, depending on your setup and widget type.
If you're not a developer and want to use XML with a spreadsheet tool, see the guide to using Custom Widgets with Excel.
Before getting started, it's also worth checking whether there's an existing data source for your use case or if the Datasets API meets your needs, as these are more flexible, easier to maintain, and receive regular improvements.
Before you start
Before building a Custom Widget, it helps to have the following figured out:
What data do you want to display, and how would you like it visualized?
How does your data source work? For example, which endpoints do you need, and how is authentication handled?
Which method is best for your setup: Push or Poll?
How will the data from your source need to be transformed to match the format Geckoboard expects?
Do you have a developer available to help you with the process?
Additionally, it’s important to note that each widget type requires a specific data format. For example, a Number Stat widget will show an error if you send it data formatted for a List widget. The full format reference for each widget type is available in the Custom Widgets developer documentation.
The process
To use Custom Widgets, you need to develop an application that requests data from your data source, transforms it into the format Geckoboard expects, and then sends it to your dashboard. Your app either sends data directly to Geckoboard (Push) or responds to a request from Geckoboard (Poll). Refer to the developer documentation for full details.
Push vs. Poll
The Push method means your app sends data directly to Geckoboard’s API. You are given a URL to send your widget data to. The main advantage of Push is that you control when data is sent. This is especially useful when your app needs time to query or process data before it is ready, since Geckoboard won’t time out waiting for a response.
The Poll method means Geckoboard periodically sends a request to a URL you provide and expects your app to respond with the widget’s data. This requires your endpoint to respond within 10 seconds. If it does not, the widget will time out.
Create a Poll widget
Click Add widget in the top right of your dashboard.
Search for Custom Widgets and select Custom Widgets LEGACY.
Select a widget type. In this example, select Line Chart.
In the widget configuration, select Poll as the method. Geckoboard will periodically send a request to the URL you provide and expects a valid data payload in response.
Paste the URL of your hosted data feed into the URL Data feed field. This can be a GitHub Gist, a Dropbox link, or any publicly accessible URL that returns the correctly formatted data. The JSON payload for a Line Chart looks like this:
{
"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
]
}
]
}Set a Reload time that makes sense for your data.
Click Add widget.
This example requires manual data updates. To keep your widget automatically up to date, you’ll need to create a script that updates the data programmatically.
Create a Push widget
Click Add widget in the top right of your dashboard.
Search for Custom Widgets and select Custom Widgets LEGACY.
Select a widget type. In this example, select RAG Column & Numbers.
In the Method field, select Push. The configuration will show only the Push URL and Widget key fields.
Click Add widget. Your new widget will appear on the dashboard.
To send data to the widget, make a POST request to the Push URL shown in the widget configuration. The Push API uses JSON exclusively, and files must be no larger than 1 MB. Here is an example using cURL:
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 over the widget, click the options icon in the top right corner, then select Edit to copy the widget’s Push URL. Replace example-widget-key in the cURL request with this value.
Replace example-api-key with your Geckoboard API key.
Update the data payload to match the format for your widget type. The RAG payload, for example, looks like this:
{
"item": [
{ "value": 16, "text": "Long past due" },
{ "value": 64, "text": "Overdue" },
{ "value": 32, "text": "Due" }
]
}Paste the complete request into your terminal and run it. If successful, you’ll receive a confirmation response, and the widget on your dashboard will update.
curl -X POST https://push.geckoboard.comv1/send/example-widget-key -d '{"api_key":"example-api-key","data":{ "item": [ { "value": 16, "text": "Long past due" }, { "value": 64, "text": "Overdue" }, { "value": 32, "text": "Due" } ] } }' -H "Content-Type:application/json"
If you’re using a Windows machine, you’ll need to escape all the quotes in the request. This example also requires manual data pushes. To keep your widget automatically up to date, you or your developer will need to write a script that pushes data programmatically.
Using Node.js
Node.js is a useful tool for getting data from a source into your Custom Widgets. The examples below assume your app has already fetched and processed the data it needs.
Push method with Node.js
Here is an example using the request-promise module from npm:
const request = require('request-promise');
const api_key = 'your API key here';
const data = {
item: [
{ value: 5723, text: 'Total paying customers' }
]
};
request({
json: true,
method: 'POST',
uri: 'https://push.geckoboard.com/v1/send/your widget key here',
body: { api_key, data },
});You’ll need your Geckoboard API key and the widget’s Push URL. Setting json: true in the options converts your JavaScript object to JSON, which is the required format for Push widgets.
Poll method with Node.js
For the Poll method, enter a URL in the widget configuration. Geckoboard will send a request to that URL and expect your app to respond with the widget data. Here is an example using the Express framework:
const express = require('express');
const server = express();
server.get('/', (req, res) => {
return res.json({
item: [
{ value: 5723, text: 'Total paying customers' }
],
});
});
server.listen(3000, () => console.log('Listening at http://localhost:3000/'));Troubleshooting
“Widget does not exist” error
If you see a “widget does not exist” message when pushing data, there are two likely causes:
The widget hasn’t been saved yet. You can only push data to a widget that has been fully saved. If you haven’t completed the setup, finish configuring your widget and click Add widget before attempting to push.
The widget was originally set to Poll and later switched to Push. In this case, delete the widget and create a new Push widget from scratch.
Poll timeout error
If your widget times out while polling, Geckoboard was unable to receive a response from your endpoint within 10 seconds. To resolve this, either optimize your application to respond faster or switch to the Push method so your app can take as long as it needs to prepare the data before sending it.