Guide to using custom widgets

Important Note: Our new Datasets feature improves on and replaces the majority of Custom Widget use. Custom Widgets are still available, but are no longer receiving updates or improvements.


Custom Widgets

This guide gives a basic overview of how you can get data onto your dashboard using your own back-end application that utilizes our Custom Widgets. It covers the following:

This is most appropriate for getting data from your own systems and databases onto your dashboards, or when Geckoboard does not already provide an Integration for the application you would like data from.

Also see our "Learn" section article Getting 'other' data on to your dashboard for using Google Sheets or CSV files to get data on to your dashboard>.

Understanding the Process

Here is a diagram explaining the way data goes from your selected data source (e.g. your own database) to your Geckoboard dashboard:

Data Source

The data that you want to see visualized on your dashboard can exist almost anywherefrom your own systems and databases to third-party APIs which we do not yet support .

Your App

Your application will send a request to the data source API (1). The data source will then reply with a response (2).


Your application will format the response from the data source into the proper widget format. The exact format depends on the type of Custom Widget you are using, and whether the widget is set to Poll or Push mode.

Your Dashboard

If you set your widget to use the Push method, your application will need to send the formatted data directly to the widget via its Push URL as a JSON payload. The Push API uses JSON exclusively. XML is not supported.

If you set up your widget to use the Poll method, your application will need to create an endpoint (i.e. a URL) that Geckoboard will send a request to (1). Your application refreshes this periodically, and the output from here is displayed on your dashboard (2). Both JSON and XML are supported in Polling mode.

Back to top

Tools Needed

Hosting and Development

You will need access to a development environment where you can host your application. How this is done is ultimately up to you in regards to your choice of operating system, programming language and application development platform. Common examples of this are using a Linux based system, such as Ubuntu with Ruby on Rails or Node.js. Geckoboard though makes no preference for how it receives your data, so your preference and what you are most comfortable with are the key deciding factors.

If you set up your widget using the Poll method, your application will need to be available at an endpoint (i.e. URL) that Geckoboard can send requests to.

If you set up your widget using the Push method, your application can remain internal (i.e. there is no need to host it publicly) as long as you can send data from your network to Geckoboard. For this method you will need your API Key and Push URL.


Your Geckoboard API key is found by clicking your avatar at the top right corner of your dashboard and choosing Account Settings.

Push URL

Push widgets send their data to a unique URL that is given in the widget set up. Once you have developed your application, add the Custom Widget to your dashboard; then choose Push for the method. Take note of this URL to use in your application.

Back to top

Application Design

Once we understand this process, we can then begin designing and implementing our custom Integration. This will generally progress in the following way:

Define the Goal

Naturally the first step is identifying the data that you want to see on your dashboard and deciding how you would like it visualized, i.e. choosing the custom widget(s) that best display the data and knowing where the data is coming from.

Understand the data source API

Once you know where your data is coming from, and how you would like to see it displayed on your dashboard, studying the API of the data source is next step in getting it into your dashboard. You want to determine how to get the data you need, and how, if it is necessary, authentication is handled.

Choose the Method: Push or Poll

Next, you should plan how the data will be delivered to your dashboard, i.e. Push or Poll.

  • Push means that your application sends the formatted data directly to the widget via its Push URL as an JSON payload. (The Push API uses JSON exclusively. XML is not supported.)
  • Poll means that Geckoboard will periodically send a request (at the frequency you configure in the widget set up) to the endpoint (i.e. URL) and expects to receive a response with the updated JSON/XML payload from your application.

Back to top


Create your application

You should now have all the elements to make it happen! You are prepared with:

  • What data you want to see on your dashboard.
  • Which widgets you will use.
  • How to access the data source API.
  • How to translate that into the appropriate payload.
  • How the payload will reach your dashboard: either the Push or Poll method

Next you will create (that is, code) your application according to your plan with the above details. Finally, add the Custom Widget to your dashboard, configuring it with the appropriate details.

You should now see your data visualized on your dashboard!

Back to top

Examples using Node.js

Here you can see some examples of creating Custom Widgets using Node.js.

Back to top



Back to top

Was this article helpful?

Thank you for your feedback!