This is a guest blog post by Dan Jenkins, a Senior Web Developer at Holiday Extras, who sell Airport Parking, Hotels, Lounges and other extras for holidays. Dan is currently in the middle of implementing Geckoboard within a few of their internal services to display metrics on call volumes, send rates and page hits to name a few.


Why did I start looking at Geckoboard?

A few weeks ago I started looking at wallboard type services out on the world wide web; and I came across Geckoboard. We've been working on our new VoIP platform for a while now and I've been keen to look at how we can create some wallboards for our Contact Centre; to show how many calls  have been answered, how many are currently waiting, how many of our Agents are currently taking calls and a few other things too.

Part of this VoIP platform has been written in NodeJS, a new technology which is around 2 years old right now. "Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices", this comes direct from the NodeJS website and explains perfectly why it's becoming so popular right now; but more importantly why we chose it to be part of our VoIP platform. When it comes to Voice over IP, if you haven't got real-time data, then there's no point having it.

So what better than Geckoboard's new Push API to go along with this real-time data? However, I hit a snag with the Push API and NodeJS being so new, there was no quick answer to trying the service out. There were no modules available on NPM for the Push API, so I made one; if you've already got NodeJs installed, you can just install the module by running the following command from within your NodeJS project:

npm install geckoboard-push


Let's talk about the geckoboard-push module

The module is completely open source and released under the MIT license; use it to your heart's content and if you'd like to contribute then submit a pull request via github.

All the docs are on github, and there's now an example site at's a sandbox dotcloud account so no guarantees about uptime!). On this example site you can change the values and send them to my test geckoboard wallboard.



How do I go about using the geckoboard-push module?

Within your application, you can include your installed module and initialise it with your API key, which you can find within your settings in geckoboard.

var Geckoboard = require('geckoboard-push');

var gecko = new Geckoboard({api_key: 'api-key'});

Then you can instantiate an object for the specific type of communication with geckoboard; your widget key is specific to a particular widget and widget type, so below you can see a variable funnel being constructed by the funnel command with the corresponding widget key. This means if you've got two funnel widgets, you could instantiate two different variables by using two different widget keys and use each variable throughout your codebase for each widget.

var funnel = gecko.funnel('widget-key');

Once you've instantiated the variable for your widget type, you can then send geckoboard some data. The data you send to geckoboard depends on each widget; you do need to check the docs for this part. For the funnel widget, you HAVE to send 3 parameters; an Array of Objects, the type and whether to show percentages; the fourth (optional) parameter is the callback.

funnel.send([{},{},{}], 'standard','show', function(response){

console.log('Funnel response from geckoboard', response);


The Array of Objects would look something like the example below, each object having a value and a label.


value: "87809",

label: "Step1"



value: "70022",

label: "Step2"




Either take a look at the module's documentation or the example site for the module, both will tell you what parameters you need to pass into each call to geckoboard. Your other option is to take a look at Geckoboard's documentation for each different widget type.


What does the module support?

The module supports each widget that's currently supported by Geckoboard's Push API:

  • Number & Secondary Stat

  • RAG Column and Numbers

  • RAG Numbers

  • Text

  • Funnel Chart

  • Bullet Graph

  • Geck-O-Meter

  • Line Chart

  • Pie Chart

  • Mapping

As soon as a new widget is supported by the Push API, it'll get added to the module; of course if something isn't supported then feel free to fork the project and submit a pull request via github. Let me know if you've used, or are thinking of using the module, if there's something missing from the module or any general comments about the module itself.