Important note: We no longer provide updates and improvements to Custom Widgets. We encourage you to try Datasets for the most simple, powerful way to access your most important data with Geckoboard.
In this article, you'll learn how to use Node.js to get data from a datasource into your Custom Widgets on your Geckoboard dashboard. It is split into two parts, covering the Push and Poll methods.
Tip: For a more general overview on using Custom Widgets, see our Custom Widgets article.
Visualization types
Each widget expects a special format, as outlined in the Custom Widgets documentation. This means, for example, that if you've added a Number Stat widget to your dashboard, it will show an error if you send it data for a List widget.
Push method
When a widget is set to use the push method, your app will send the data directly to a URL given in the widget config page.
Or copied from the widget on the dashboard.
Imagining that your app has already requested the data it needs to build your metrics, it then sends that data to the widget endpoint. Here is an example that uses the request 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 can see here that:
You need your API key.
The widget’s endpoint (or Push URL, as seen above).
That the expected format for the body is:
{
api_key: "you API key here",
data: {} // the widget payload
}Also note that using the request module, we set in the options json to true. This takes our plain JavaScript object and turns it into JSON, which is the required format for Push widgets.
Poll method
For the Poll method, you enter a URL in the widget’s configuration.
Then Geckoboard will send a request to that URL, expecting to receive your widget’s data in response.
Again, imagining that you’ve already done the fetching and processing of the data you want in the widget, here’s an example of using the popular Express framework to send a response to Geckoboard’s request:
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/'));