Overview

Introduction

This documentation is intended as a reference for developing around Geckoboard's custom widgets, i.e. how to format and send your custom data to your Geckoboard dashboards. It details the supported visualizations and parameters and options that you can tweak to get the most out of your data.

If you get stuck, have trouble, or need a hand, then you may want to..

Check out a step by step guide on our support site
Chat with other customers like yourself in our Developer Community
Reach out to our friendly neighborhood support team -- they'd love to help!

Changelog

See below for a record of recent changes to the Geckoboard API.

21 April 2015

We've increased our Push API rate limit to 12,000 requests per hour, and updated the relevant section of our documentation accordingly.

19 February 2015

Added a section for the new Bar/Column chart custom widget type.

12 February 2015

The Line Chart section has been rewritten following the release of the new and improved line chart.

3 December 2014

The Push API Errors section has been rewritten to reflect some recent changes in behaviour. The API will now respond with new, more meaningful HTTP status codes when an error is encountered. In addition, widget validation errors will no longer be included in the HTTP response.

19 November 2014

Added a section on how to configure Goals for Number and Geck-o-Meter custom widgets.

27 October 2014

Added a section for the new Leaderboard custom widget type.

Widget Types

Custom Widget Types

There are a number of different custom widget types that you can use to display your data. Each type provides a different visualisation and requires a different data format.

Bar Chart

Bar chart

The bar chart visualisation is best suited to discrete, categorical data. Example uses include seeing a breakdown of the number of support tickets by current status, or the sales of your product line by year.

Supported Sizes

This widget supports all available sizes.

Parameters

series

An array containing up to three data series objects.

data: An array of data points for the bar chart. Each data point may be given as a single number, such as [3, 5, 8].

x_axis

Optional configuration options for the X axis.

labels optional: An array of strings specifying the labels for each of the data points in the series.

type optional: Specifying the string "datetime" will cause all X-axis labels to be interpreted as an ISO 8601 date/time. Partial dates (e.g. 2014-10 for October 2014) are supported. Leaving type empty or setting it to standard will cause X values to be interpreted the usual way.

y_axis

Optional configuration options for the Y axis.

format optional: If given, this string will represent the format of the Y axis and will be displayed accordingly. Possible values are "decimal", "percent" and "currency". The default is "decimal".

unit optional: When the format is currency this must be an ISO 4217 currency code. E.g. "GBP", "USD", "EUR".

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <x_axis>
    <labels>2000</labels>
    <labels>2001</labels>
    <labels>2002</labels>
    <labels>2003</labels>
    <labels>2004</labels>
    <labels>2005</labels>
  </x_axis>
  <y_axis>
    <format>currency</format>
    <unit>USD</unit>
  </y_axis>
  <series>
    <data>1000</data>
    <data>1500</data>
    <data>30600</data>
    <data>28800</data>
    <data>22300</data>
    <data>36900</data>
  </series>
</root>

{
  "x_axis": {
    "labels": [
      "2000",
      "2001",
      "2002",
      "2003",
      "2004",
      "2005"
    ]
  },
  "y_axis": {
    "format": "currency",
    "unit": "USD"
  },
  "series": [
    {
      "data": [
        1000,
        1500,
        30600,
        28800,
        22300,
        36900
      ]
    }
  ]
}

Simple Example

Simple bar chart

This example demonstrates the usage of a "simple" bar chart with the distribution of support tickets by status.

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <x_axis>
    <labels>open</labels>
    <labels>pending</labels>
    <labels>solved</labels>
    <labels>closed</labels>
  </x_axis>
  <series>
    <data>45</data>
    <data>4</data>
    <data>251</data>
    <data>554</data>
  </series>
</root>

{
  "x_axis": {
    "labels": ["open", "pending", "solved", "closed"]
  },
  "series": [
    {
      "data": [45, 4, 251, 554]
    }
  ]
}

Datetime example

Bar chart with datetime

Settings the X axis type option to "datetime" causes the array of strings provided as labels to be interpreted as ISO 8601 date/time specifiers. Please note that partial dates, such as "2014", "2014-01", etc. are supported and may be provided.

{
  "x_axis": {
    "type": "datetime",
    "labels": [
      "2014-01",
      "2014-02",
      "2014-03",
      "2014-04",
      "2014-05",
      "2014-06"
    ]
  },
  "series": [
    {
      "data": [
        71173,
        57624,
        64851,
        60486,
        60500,
        62908
      ]
    }
  ]
}

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <x_axis>
    <type>datetime</type>
    <labels>2014-01</labels>
    <labels>2014-02</labels>
    <labels>2014-03</labels>
    <labels>2014-04</labels>
    <labels>2014-05</labels>
    <labels>2014-06</labels>
  </x_axis>
  <series>
    <data>71173</data>
    <data>57624</data>
    <data>64851</data>
    <data>60486</data>
    <data>60500</data>
    <data>62908</data>
  </series>
</root>

Multiseries example

Bar chart with multiseries

You can add additional elements to the series array in order to produce a multiseries bar chart.

{
  "x_axis": {
    "labels": [
      "2000",
      "2001",
      "2002",
      "2003",
      "2004",
      "2005"
    ]
  },
  "y_axis": {
    "format": "currency",
    "unit": "USD"
  },
  "series": [
    {
      "name": "Apples",
      "data": [
        1000,
        1500,
        30600,
        28800,
        22300,
        36900
      ]
    },
    {
      "name": "Bananas",
      "data": [
        2000,
        3000,
        40600,
        58800,
        42300,
        76900
      ]
    },
    {
      "name": "Pears",
      "data": [
        4000,
        5500,
        70600,
        88800,
        62300,
        86900
      ]
    }
  ]
}

<?xml version="1.0" encoding="UTF-8" ?>
    <root>
    <x_axis>
        <labels>2000</labels>
        <labels>2001</labels>
        <labels>2002</labels>
        <labels>2003</labels>
        <labels>2004</labels>
        <labels>2005</labels>
    </x_axis>
    <y_axis>
        <format>currency</format>
        <unit>USD</unit>
    </y_axis>
    <series>
        <name>Apples</name>
        <data>1000</data>
        <data>1500</data>
        <data>30600</data>
        <data>28800</data>
        <data>22300</data>
        <data>36900</data>
    </series>
    <series>
        <name>Bananas</name>
        <data>2000</data>
        <data>3000</data>
        <data>40600</data>
        <data>58800</data>
        <data>42300</data>
        <data>76900</data>
    </series>
    <series>
        <name>Pears</name>
        <data>4000</data>
        <data>5500</data>
        <data>70600</data>
        <data>88800</data>
        <data>62300</data>
        <data>86900</data>
    </series>
</root>

Bullet Graph

A bullet graph is an extremely efficient and flexible way to communicate a lot of information in a way that's easy to interpret and digest.

It is very useful when you want to track progress towards a goal. A good example of a metric for this visualisation would be a sales or revenue target.

Supported Sizes

2 x 1
1 x 2
2 x 2

Parameters

range

A bullet graph is divided into three contiguous ranges, each of which is identifiable by a different background colour:

Red: the result is far below expectations
Amber: the result is neither good nor bad
Green: results in this range have met or exceeded expectations

The range array contains three objects, each of which represents the size and extent of each of the portions of the bullet graph. Each of the range objects must contain the following parameters.

color: This parameter identifies the range by its colour. The only allowed values are red, amber, and green.

start: This numeric parameter indicates the amount at which this range starts.

end: This numeric parameter indicates the amount at which this range ends.

measure

The measure object allows you to specify two ranges to help contextualise your data. Each of them uses the same start/end format as the range objects above.

current: This range represents the current value and will be filled with the black line.

projected: This range will be filled with a white translucent line and represents the value you expect to achieve , given past performance. For example, if revenue so far is $1,000 and it's the 15th day of the month, you could set the end of this range to 2000.

comparative

The optional comparative object allows you to specify one or more values that you wish to compare with the current value. For example, last year's revenue, or a goal that you would like to share with your team.

point: This parameter may be set to either a number, in the case of a single comparative point, or an array of numbers, for multiple comparative points.

orientation

The optional orientation parameter allows you to specify the orientation of the bullet: either horizontal or vertical. Certain widget sizes only work for certain orientations.

2 x 1: horizontal only
1 x 2: vertical only
2 x 2: both orientations are valid (default: horizontal)

Additional Parameters

axis: Specify the points on the axis by passing in a point array of numbers.

label: The main label displayed next to the bullet graph.

sublabel: optional An optional sublabel. This is often used to indicate the units of the graph.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <orientation>horizontal</orientation>
  <item>
    <label>Revenue 2014 YTD</label>
    <sublabel>(U.S. $ in thousands)</sublabel>
    <axis>
      <point>0</point>
      <point>200</point>
      <point>400</point>
      <point>600</point>
      <point>800</point>
      <point>1000</point>
    </axis>
    <range>
      <red>
        <start>0</start>
        <end>400</end>
      </red>
      <amber>
        <start>401</start>
        <end>700</end>
      </amber>
      <green>
        <start>701</start>
        <end>1000</end>
      </green>
    </range>
    <measure>
      <current>
        <start>0</start>
        <end>500</end>
      </current>
      <projected>
        <start>100</start>
        <end>900</end>
      </projected>
    </measure>
    <comparative>
      <point>600</point>
    </comparative>
  </item>
</root>

{
  "orientation": "horizontal",
  "item": {
    "label": "Revenue 2014 YTD",
    "sublabel": "(U.S. $ in thousands)",
    "axis": {
      "point": ["0", "200", "400", "600", "800", "1000"]
    },
    "range": {
      "red": {
        "start": 0,
        "end": 400
      },
      "amber": {
        "start": 401,
        "end": 700
      },
      "green": {
        "start": 701,
        "end": 1000
      }
    },
    "measure": {
      "current": {
        "start": "0",
        "end": "500"
      },
      "projected": {
        "start": "100",
        "end": "900"
      }
    },
    "comparative": {
      "point": "600"
    }
  }
}

Multiple bullet graphs

You can only display a single bullet graph in a 1×2 or 2×1 widget.

However, you can display up to 4 bullet graphs in a 2×2 widget by specifying multiple bullets under the item key.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <orientation>vertical</orientation>
  <item>
    <label>Revenue</label>
    <sublabel>U.S. $ (1,000s)</sublabel>
    <axis>
      <point>0</point>
      <point>50</point>
      <point>100</point>
      <point>150</point>
      <point>200</point>
      <point>250</point>
    </axis>
    <range>
      <red>
        <start>0</start>
        <end>125</end>
      </red>
      <amber>
        <start>126</start>
        <end>200</end>
      </amber>
      <green>
        <start>201</start>
        <end>250</end>
      </green>
    </range>
    <measure>
      <current>
        <start>0</start>
        <end>235</end>
      </current>
    </measure>
    <comparative>
      <point>220</point>
    </comparative>
  </item>
  <item>
    <label>Expenses</label>
    <sublabel>U.S. $ (1,000s)</sublabel>
    <axis>
      <point>0</point>
      <point>30</point>
      <point>60</point>
      <point>90</point>
      <point>120</point>
      <point>150</point>
    </axis>
    <range>
      <red>
        <start>91</start>
        <end>150</end>
      </red>
      <green>
        <start>0</start>
        <end>50</end>
      </green>
      <amber>
        <start>51</start>
        <end>90</end>
      </amber>
    </range>
    <measure>
      <current>
        <start>0</start>
        <end>65</end>
      </current>
    </measure>
    <comparative>
      <point>80</point>
    </comparative>
  </item>
  <item>
    <label>Avg Order</label>
    <sublabel>U.S. $</sublabel>
    <axis>
      <point>0</point>
      <point>100</point>
      <point>200</point>
      <point>300</point>
      <point>400</point>
      <point>500</point>
    </axis>
    <range>
      <red>
        <start>0</start>
        <end>250</end>
      </red>
      <amber>
        <start>251</start>
        <end>400</end>
      </amber>
      <green>
        <start>401</start>
        <end>500</end>
      </green>
    </range>
    <measure>
      <current>
        <start>0</start>
        <end>230</end>
      </current>
    </measure>
    <comparative>
      <point>450</point>
    </comparative>
  </item>
  <item>
    <label>Cust Sat</label>
    <sublabel>Top Rating of 5</sublabel>
    <axis>
      <point>0</point>
      <point>1</point>
      <point>2</point>
      <point>3</point>
      <point>4</point>
      <point>5</point>
    </axis>
    <range>
      <red>
        <start>0</start>
        <end>3.3</end>
      </red>
      <amber>
        <start>3.4</start>
        <end>4.25</end>
      </amber>
      <green>
        <start>4.26</start>
        <end>5</end>
      </green>
    </range>
    <measure>
      <current>
        <start>0</start>
        <end>4.6</end>
      </current>
    </measure>
    <comparative>
      <point>4.3</point>
    </comparative>
  </item>
</root>

{
  "orientation": "vertical",
  "item": [
    {
      "axis": {
        "point": [
          "0",
          "50",
          "100",
          "150",
          "200",
          "250"
        ]
      },
      "comparative": {
        "point": "220"
      },
      "label": "Revenue",
      "measure": {
        "current": {
          "end": "235",
          "start": "0"
        }
      },
      "range": {
        "red": {
          "end": "125",
          "start": "0"
        },
        "amber": {
          "end": "200",
          "start": "126"
        },
        "green": {
          "end": "250",
          "start": "201"
        }
      },
      "sublabel": "U.S. $ (1,000s)"
    },
    {
      "axis": {
        "point": [
          "0",
          "30",
          "60",
          "90",
          "120",
          "150"
        ]
      },
      "comparative": {
        "point": "80"
      },
      "label": "Expenses",
      "measure": {
        "current": {
          "end": "65",
          "start": "0"
        }
      },
      "range": {
        "red": {
          "end": "150",
          "start": "91"
        },
        "amber": {
          "end": "90",
          "start": "51"
        },
        "green": {
          "end": "50",
          "start": "0"
        }
      },
      "sublabel": "U.S. $ (1,000s)"
    },
    {
      "axis": {
        "point": [
          "0",
          "100",
          "200",
          "300",
          "400",
          "500"
        ]
      },
      "comparative": {
        "point": "450"
      },
      "label": "Avg Order",
      "measure": {
        "current": {
          "end": "230",
          "start": "0"
        }
      },
      "range": {
        "red": {
          "end": "250",
          "start": "0"
        },
        "amber": {
          "end": "400",
          "start": "251"
        },
        "green": {
          "end": "500",
          "start": "401"
        }
      },
      "sublabel": "U.S. $"
    },
    {
      "axis": {
        "point": [
          "0",
          "1",
          "2",
          "3",
          "4",
          "5"
        ]
      },
      "comparative": {
        "point": "4.3"
      },
      "label": "Cust Sat",
      "measure": {
        "current": {
          "end": "4.6",
          "start": "0"
        }
      },
      "range": {
        "red": {
          "end": "3.3",
          "start": "0"
        },
        "amber": {
          "end": "4.25",
          "start": "3.4"
        },
        "green": {
          "end": "5",
          "start": "4.26"
        }
      },
      "sublabel": "Top Rating of 5"
    }
  ]
}

Funnel

The funnel visualisation allows you to show how a number of stages (typically called a funnel) are performing. A good example of this would be the number of users who do the following on a website:

Visit your website
Sign up for a free trial
Convert to a paying customer

A funnel only really makes sense if the number of "things" happening at each stage decreases or stays constant at each stage.

Supported Sizes

2 x 1 (this funnel only has 3 stages)
2 x 2 (this funnel can have between 3 and 8 stages)

Parameters

item : required This is an ordered array of objects. Each object is a subsequent step down the funnel which expects the parameters value (required) and an optional label.

percentage: optional If this is set to hide then the percentage values will be hidden from the visualisation.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <value>87809</value>
    <label>Step 1</label>
  </item>
  <item>
    <value>70022</value>
    <label>Step 2</label>
  </item>
  <item>
    <value>63232</value>
    <label>Step 3</label>
  </item>
  <item>
    <value>53232</value>
    <label>Step 4</label>
  </item>
  <item>
    <value>32123</value>
    <label>Step 5</label>
  </item>
  <item>
    <value>23232</value>
    <label>Step 6</label>
  </item>
  <item>
    <value>12232</value>
    <label>Step 7</label>
  </item>
  <item>
    <value>2323</value>
    <label>Step 8</label>
  </item>
</root>

{
  "item":[
    {
      "value":"87809",
      "label":"Step1"
    },
    {
      "value":"70022",
      "label":"Step2"
    },
    {
      "value":"63232",
      "label":"Step 3"
    },
    {
      "value":"53232",
      "label":"Step 4"
    },
    {
      "value":"32123",
      "label":"Step 5"
    },
    {
      "value":"23232",
      "label":"Step 6"
    },
    {
      "value":"12232",
      "label":"Step 7"
    },
    {
      "value":"2323",
      "label":"Step 8"
    }
  ]
}

Gauge

Geck-o-meter

The Gauge widget is used to display a numeric value within the context of its minimum/maximum range.

An example of this would be a Gauge displaying the number of current visitors on a particular website, where the minimum and maximum values could represent the smallest and largest number of concurrent visitors seen within a particular time range (such as the last 24 hours).

Supported Sizes

1 x 1
2 x 2

Parameters

item: A numeric parameter representing the current value of the Gauge.

min/max: The required sections min and max provide the data for the minimum and maximum value of the Gauge, respectively.

value: The numeric value for the minimum/maximum value of the Gauge.

format optional: If given, this string will represent the format of the Gauge value and min/max and they will be displayed accordingly. Possible values are "percent" and "currency".

unit optional: When the format is currency this must be an ISO 4217 currency code. E.g. "GBP", "USD", "EUR"

Goals

You can add an optional goal from the Set up Widget screen in the app.

Geck-o-meter with goal

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>23</item>
  <min>
    <value>10</value>
  </min>
  <max>
    <value>30</value>
  </max>
</root>

{
  "item": 23,
  "min": {
    "value": 10
  },
  "max": {
    "value": 30
  }
}

Highcharts

Highcharts is a powerful charting library that supports many different ways of visualising data. Use this if you're trying to visualise in a way that isn't supported in the other visualisations. Bear in mind that Highcharts can be quite difficult to configure correctly, and that only the core Highcharts library is supported. See the 'Known Limitations' section for full compatibility information.

Supported Sizes

1 x 1
2 x 1
1 x 2
2 x 2
3 x 2
4 x 2

Known Limitations

We currently support the following chart types:
Line
Spline
Area
Areaspline
Column
Bar
Pie
Scatter
Highcharts plugins and extensions - for example highcharts-more.js - are not supported at this time.

Parameters

The payload for this visualisation is based on the structure you would use if you were using Highcharts in your own JavaScript. For more details, see the official Highcharts documentation.

One thing to note is that it is JavaScript, not JSON:

{
  chart: {
    renderTo: 'container'
  },
  credits: {
    enabled: false
  },
  series: {
    // YOUR DATA POINTS HERE
  }
}

See the Highcharts options reference for complete documentation and view their chart demo gallery to get an idea of the types of charts you can create in Geckoboard.

Push API Usage

For Push widgets, the JavaScript definition needs to be converted to a string and then passed in as the value to a key called highchart. Please note that all strings inside the JavaScript payload need to be escaped.

{
  "api_key": "YOUR_API_KEY",
  "data": {
    "highchart": "{\"chart\": {\"renderTo\": \"container\", ...}, \"series\": {...}"
  }
}

Here’s a quick example of how to push some data via cURL:

curl https://push.geckoboard.com/v1/send/[WIDGET ID] -d '{"api_key":"[API KEY]", "data":{"highchart": "{chart:{style: {color: \"#b9bbbb\"},renderTo:\"container\",backgroundColor:\"transparent\",lineColor:\"rgba(35,37,38,100)\",plotShadow: false,},credits:{enabled:false},title:{style: {color: \"#b9bbbb\"},text:\"Monthly Average Temperature\"},xAxis:{categories:[\"Jan\",\"Feb\",\"Mar\",\"Apr\",\"May\",\"Jun\",\"Jul\",\"Aug\",\"Sep\",\"Oct\",\"Nov\",\"Dec\"]},yAxis:{title:{style: {color: \"#b9bbbb\"}, text:\"Temperature\"}},legend:{itemStyle: {color: \"#b9bbbb\"}, layout:\"vertical\",align:\"right\",verticalAlign:\"middle\",borderWidth:0},series:[{color:\"#108ec5\",name:\"NewYork\",data:[17.0,22.0,24.8,24.1,20.1,14.1,8.6,2.5]},{color:\"#52b238\",name:\"Berlin\",data:[13.5,17.0,18.6,17.9,14.3,9.0,3.9,1.0]},{color:\"#ee5728\",name:\"London\",data:[11.9,15.2,17.0,16.6,14.2,10.3,6.6,4.8]}]}"}}'

Highcharts Example

This is an example of a Highchart-powered line plot that displays the monthly average temperature for 3 distinct cities.

Simple Highcharts example

{
  chart: {
    style: {
      color: "#b9bbbb"
    },
    renderTo: "container",
    backgroundColor: "transparent",
    lineColor: "rgba(35,37,38,100)",
    plotShadow: false
  },
  credits: {
    enabled: false
  },
  title: {
    style: {
      color: "#b9bbbb"
    },
    text: "Monthly Average Temperature"
  },
  xAxis: {
    categories: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
  },
  yAxis: {
    title: {
      style: {
        color: "#b9bbbb"
      },
      text: "Temperature"
    }
  },
  legend: {
    itemStyle: {
      color: "#b9bbbb"
    },
    layout: "vertical",
    align: "right",
    verticalAlign: "middle",
    borderWidth: 0
  },
  series: [{
    color: "#108ec5",
    name: "NewYork",
    data: [17.0, 22.0, 24.8, 24.1, 20.1, 14.1, 8.6, 2.5]
  }, {
    color: "#52b238",
    name: "Berlin",
    data: [13.5, 17.0, 18.6, 17.9, 14.3, 9.0, 3.9, 1.0]
  }, {
    color: "#ee5728",
    name: "London",
    data: [11.9, 15.2, 17.0, 16.6, 14.2, 10.3, 6.6, 4.8]
  }]
}

Leaderboard

Leaderboard widget

Supported Sizes

1 × 1
1 × 2
1 × 3
1 × 4
2 × 2
2 × 3
2 × 4

Parameters

`items`

A list of up to 22 items. These specify the label and optionally value and previous_rank of each item in the Leaderboard.

Rank order will follow the order of items in the list.

The following table lists how many items will be displayed for each available widget height.

Height	Max Items
1	4
2	10
3	16
4	22

label: The text to display – Only plain text is supported, so no HTML.

value: optional Useful for giving some context to the ranking. E.g. Total sales this month. If a number is passed it will be formatted according to your browser's locale.

previous_rank: optional The previous rank of this item (1-indexed). This will be used to indicate the last movement of this item in the rankings.

`format`

optional Possible values are "decimal", "percent" and "currency". The default is "decimal".

`unit`

optional When the format is currency this must be an ISO 4217 currency code. E.g. "GBP", "USD", "EUR"

{
  "items": [
    {
      "label": "Peter",
      "value": 234,
      "previous_rank": 2
    },
    {
      "label": "Patrick",
      "value": 232,
      "previous_rank": 1
    },
    {
      "label": "Jon",
      "value": 230
    },
    {
      "label": "Clara",
      "value": 220
    },
    {
      "label": "Tom",
      "value": 215,
      "previous_rank": 7
    },
    {
      "label": "Sylvester",
      "value": 200
    },
    {
      "label": "David",
      "value": 195,
      "previous_rank": 5
    },
    {
      "label": "Matt",
      "value": 190
    },
    {
      "label": "William",
      "value": 185
    },
    {
      "label": "Rose",
      "value": 182,
      "previous_rank": 11
    },
    {
      "label": "Colin",
      "value": 178,
      "previous_rank": 10
    },
    {
      "label": "Paul",
      "value": 172
    },
    {
      "label": "Amy",
      "value": 166
    },
    {
      "label": "Christopher",
      "value": 162
    }
  ]
}

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <items>
    <label>Peter</label>
    <value>234</value>
    <previous_rank>2</previous_rank>
  </items>
  <items>
    <label>Patrick</label>
    <value>232</value>
    <previous_rank>1</previous_rank>
  </items>
  <items>
    <label>Jon</label>
    <value>230</value>
  </items>
  <items>
    <label>Clara</label>
    <value>220</value>
  </items>
  <items>
    <label>Tom</label>
    <value>215</value>
    <previous_rank>7</previous_rank>
  </items>
  <items>
    <label>Sylvester</label>
    <value>200</value>
  </items>
  <items>
    <label>David</label>
    <value>195</value>
    <previous_rank>5</previous_rank>
  </items>
  <items>
    <label>Matt</label>
    <value>190</value>
  </items>
  <items>
    <label>William</label>
    <value>185</value>
  </items>
  <items>
    <label>Rose</label>
    <value>182</value>
    <previous_rank>11</previous_rank>
  </items>
  <items>
    <label>Colin</label>
    <value>178</value>
    <previous_rank>10</previous_rank>
  </items>
  <items>
    <label>Paul</label>
    <value>172</value>
  </items>
  <items>
    <label>Amy</label>
    <value>166</value>
  </items>
  <items>
    <label>Christopher</label>
    <value>162</value>
  </items>
</root>

Formatting values

If a value is numeric we will attempt to format it to your browser's locale settings using the formatting options you provide.

An example of a Leaderboard with currency formatting applied

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <format>currency</format>
  <unit>GBP</unit>
  <items>
    <label>Peter</label>
    <value>234</value>
  </items>
  <items>
    <label>Patrick</label>
    <value>232</value>
  </items>
  <items>
    <label>Jon</label>
    <value>230.45</value>
  </items>
  <items>
    <label>Clara</label>
    <value>220</value>
  </items>
  <items>
    <label>Tom</label>
    <value>215.578</value>
  </items>
  <items>
    <label>Sylvester</label>
    <value>200</value>
  </items>
  <items>
    <label>David</label>
    <value>195</value>
  </items>
  <items>
    <label>Matt</label>
    <value>190</value>
  </items>
  <items>
    <label>William</label>
    <value>185.679</value>
  </items>
  <items>
    <label>Rose</label>
    <value>182</value>
  </items>
</root>

{
  "format": "currency",
  "unit": "GBP",
  "items": [
    {
      "label": "Peter",
      "value": 234.4
    },
    {
      "label": "Patrick",
      "value": 232
    },
    {
      "label": "Jon",
      "value": 230.45
    },
    {
      "label": "Clara",
      "value": 220
    },
    {
      "label": "Tom",
      "value": 215.578
    },
    {
      "label": "Sylvester",
      "value": 200
    },
    {
      "label": "David",
      "value": 195
    },
    {
      "label": "Matt",
      "value": 190
    },
    {
      "label": "William",
      "value": 185.679
    },
    {
      "label": "Rose",
      "value": 182
    }
  ]
}

Line Chart

Line Chart widget

The line chart visualisation is best suited for showing how one or more metrics change over time.

An example use would be displaying the number of website visitors per day, or sales per month.

The following covers version 2 of our line chart visualisation. If you're looking for documentation on the version 1 API format, please refer to the archive.

Supported Sizes

The line chart visualisation supports all available sizes.

Parameters

series

An array of one or more data series objects. Each series will correspond to a separate line in the chart. The following options are available for each series:

data: An array of data points for the line chart. Each data point may be given as a single number (e.g. [3, 5, 8]), or as a two-element array specifying both X and Y axis values, respectively (e.g. [[0, 1], [1, 5], [2, 25]]). While the Y axis value must be a number, the X axis value may be a string, if the datetime option is used. See the datetime example below for details.

name optional: An optional string indicating the name of the series. This will be displayed in the line chart's legend.

incomplete_from optional: This option will mark the series as incomplete from that point onwards. This is useful, for example, for displaying visitors per day to a website, while making it clear that today's data doesn't yet correspond to the full time interval. Note that incomplete_from includes the value provided, as well as any subsequent ones and is only available when using scatter-style charts. See the datetime example below for an example of this property in use.

type optional: Can be either "main", or "secondary", defaults to "main" if not specified. A series of type "main" will be represented by a solid line in the chart, will be labelled in the legend, and can have a goal state. A "secondary" series will have a grey dashed line, will not show up in the legend, and cannot have a goal state. "secondary" series are useful for comparing current performance to previous values. For example, comparing revenue from this month (the "main" series), to last month's revenue (the "secondary" series).

x_axis

Optional configuration options for the X axis.

labels optional: An array of strings, or numbers, to be used for populating simple line charts. Providing labels for a scatter-style plot will result in an error.

type optional: Specifying the string "datetime" will cause all X axis values to be interpreted as an ISO 8601 date/time. Partial dates (e.g. 2014-10 for October 2014) are supported. See below for details on how datetimes are rendered on the chart. Leaving type empty or setting it to standard will cause X values to be interpreted the usual way.

y_axis

Optional configuration options for the Y axis.

format optional: If given, this string will represent the format of the Y axis and will be displayed accordingly. Possible values are "decimal", "percent" and "currency". The default is "decimal".

unit optional: When the format is currency this must be an ISO 4217 currency code. E.g. "GBP", "USD", "EUR"

Notes on datetime handling

Rendered precision

When x-values are provided as datetimes, the line chart optimises the level of precision displayed on the x-axis based on the size of the widget and the overall time span.

Timezones

If values of time are provided, e.g. "2015-09-15T13:00", the dashboard will treat these as local to the dashboard's time zone setting and will not adjust them. That is, no matter what the dashboard's time zone is configured to, the values will remain the same.

If you would like the dashboard to adjust the values relative to its configured time zone, an ISO 8601 time zone identifier must be appended to the time string, such as "2015-09-15T13:00Z" or "2015-09-15T13:00+00:00" where here the "Z" or "00:00" indicates UTC.

For example, if the dashboard's time zone were set to Honolulu, the datetime value of "2015-09-15T13:00+00:00", which is UTC, would be converted to and displayed as the local time of "2015-09-15T02:00".

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <y_axis>
    <format>currency</format>
    <unit>USD</unit>
  </y_axis>
  <series>
    <name>GBP -> USD</name>
    <data>1.62529</data>
    <data>1.56991</data>
    <data>1.50420</data>
    <data>1.52265</data>
    <data>1.55356</data>
    <data>1.51930</data>
    <data>1.52148</data>
    <data>1.51173</data>
    <data>1.55170</data>
    <data>1.61966</data>
    <data>1.59255</data>
    <data>1.63762</data>
  </series>
</root>

{
  "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
      ]
    }
  ]
}

Simple Example

Simple Line Chart widget

This example demonstrates the usage of "simple" data series: that is, the ones without explicit X axis values. The optional labels option for the X axis is used to add a caption for the month name at the right intervals.

{
  "x_axis": {
    "labels": [
      "Jan", "Feb", "Mar", "Apr",
      "May", "Jun", "Jul", "Aug",
      "Sep", "Oct", "Nov", "Dec"
    ]
  },
  "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
      ]
    },
    {
      "name": "GBP -> EUR",
      "data": [
        1.23226, 1.15025, 1.15501, 1.18526,
        1.18137, 1.16923, 1.16434, 1.14420,
        1.17542, 1.19759, 1.18098, 1.20513
      ]
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <x_axis>
    <labels>Jan</labels>
    <labels>Feb</labels>
    <labels>Mar</labels>
    <labels>Apr</labels>
    <labels>May</labels>
    <labels>Jun</labels>
    <labels>Jul</labels>
    <labels>Aug</labels>
    <labels>Sep</labels>
    <labels>Oct</labels>
    <labels>Nov</labels>
    <labels>Dev</labels>
  </x_axis>
  <series>
    <name>GBP -> USD</name>
    <data>1.62529</data>
    <data>1.56991</data>
    <data>1.50420</data>
    <data>1.52265</data>
    <data>1.55356</data>
    <data>1.51930</data>
    <data>1.52148</data>
    <data>1.51173</data>
    <data>1.55170</data>
    <data>1.61966</data>
    <data>1.59255</data>
    <data>1.63762</data>
  </series>
  <series>
    <name>GBP -> EUR</name>
    <data>1.23226</data>
    <data>1.15025</data>
    <data>1.15501</data>
    <data>1.18526</data>
    <data>1.18137</data>
    <data>1.16923</data>
    <data>1.16434</data>
    <data>1.14420</data>
    <data>1.17542</data>
    <data>1.19759</data>
    <data>1.18098</data>
    <data>1.20513</data>
  </series>
</root>

Labels Example

Line Chart widget with labels

When specifying labels for the values on the x-axis, the label array should only contain strings.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <x_axis>
    <labels>May</labels>
    <labels>Jun</labels>
    <labels>Jul</labels>
    <labels>Aug</labels>
    <labels>Sep</labels>
  </x_axis>
  <series>
    <data>10</data>
    <data>2</data>
    <data>24</data>
    <data>18</data>
    <data>35</data>
  </series>
</root>

{
  "x_axis": {
    "labels": ["May", "Jun", "Jul", "Aug", "Sep"]
  },
  "series": [
    {
      "data": [
        10, 2, 24, 18, 35
      ]
    }
  ]
}

Scatter Example

Line Chart widget (scatter)

This example shows how pairs of [X, Y] data points may be provided. Note that these may come in any order, and that the X values may be different or missing across multiple data series.

{
  "series": [
    {
      "name": "sin(x)",
      "data": [
        [0, 0],
        [0.785, 0.5],
        [1.57, 1],
        [2.093, 0.5],
        [3.14, 0]
      ]
    },
    {
      "name": "cos(x)",
      "data": [
        [0, 1],
        [0.785, 0.5],
        [1.57, 0],
        [2.093, 0.5],
        [3.14, 1]
      ]
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <series>
    <name>sin(x)</name>
    <data><x>0</x><y>0</y></data>
    <data><x>0.785</x><y>0.5</y></data>
    <data><x>1.57</x><y>1</y></data>
    <data><x>2.093</x><y>0.5</y></data>
    <data><x>3.14</x><y>0</y></data>
  </series>
  <series>
    <name>cos(x)</name>
    <data><x>0</x><y>1</y></data>
    <data><x>0.785</x><y>0.5</y></data>
    <data><x>1.57</x><y>0</y></data>
    <data><x>2.093</x><y>0.5</y></data>
    <data><x>3.14</x><y>1</y></data>
  </series>
</root>

Datetime example

Line Chart widget (datetime)

Setting the X axis' type option to "datetime" allows for strings to be provided as the X axis value of each of the data points. All strings must be valid ISO 8601 specifiers. The data points may come in any order, and they will be sorted from earliest to latest. Formatting of the X axis labels will depend on the granularity of the data: points separated by a few minutes will be displayed as time of day, whereas longer intervals may be displayed as dates, months, or years.

Note that the incomplete_from option causes the line to be dotted for data points starting from (and including) October 2014, indicating that the value is not yet final.

{
  "x_axis": {
    "type": "datetime"
  },
  "series": [
    {
      "name": "Visitors per month",
      "data": [
        ["2014-01", 71173],
        ["2014-02", 57624],
        ["2014-03", 64851],
        ["2014-04", 60486],
        ["2014-05", 60500],
        ["2014-06", 62908],
        ["2014-07", 64818],
        ["2014-08", 59961],
        ["2014-09", 58542],
        ["2014-10", 22050]
      ],
      "incomplete_from": "2014-10"
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <x_axis>
    <type>datetime</type>
  </x_axis>
  <series>
    <name>Visitors per month</name>
    <data><x>2014-01</x><y>71173</y></data>
    <data><x>2014-02</x><y>57624</y></data>
    <data><x>2014-03</x><y>64851</y></data>
    <data><x>2014-04</x><y>60486</y></data>
    <data><x>2014-05</x><y>60500</y></data>
    <data><x>2014-06</x><y>62908</y></data>
    <data><x>2014-07</x><y>64818</y></data>
    <data><x>2014-08</x><y>59961</y></data>
    <data><x>2014-09</x><y>58542</y></data>
    <data><x>2014-10</x><y>22050</y></data>
    <incomplete_from>2014-10</incomplete_from>
  </series>
</root>

List

List widget

The list widget displays a paginated list of text lines.

An example of this would be a List to show the top domains referring traffic to your site.

The list widget can paginate between 1 and 9 pages. A different number of elements is displayed on each page depending on the size of the widget.

Supported Sizes

1 × 1
2 × 1
2 × 2

Parameters

Each object must have a title key with at least a text attribute.

text: The text to display – Only text data is supported, so no HTML.

name: optional The label is only visible in 2×2 sized widgets and lets you display a label in front of the title with a background colour of your choice.

color: optional Accepts every valid CSS colour (#f1e, red… default value is #b5712b).

description: optional The description defines the sub-text displayed under the title.

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <item>
    <title>
      <text>Chrome</text>
    </title>
    <label>
      <name>New!</name>
      <color>#ff2015</color>
    </label>
    <description>40327 visits</description>
  </item>
  <item>
    <title>
      <text>Safari</text>
    </title>
    <description>11577 visits</description>
  </item>
  <item>
    <title>
      <text>Firefox</text>
    </title>
    <description>10296 visits</description>
  </item>
  <item>
    <title>
      <text>Internet Explorer</text>
    </title>
    <description>3587 visits</description>
  </item>
  <item>
    <title>
      <text>Opera</text>
    </title>
    <description>499 visits</description>
  </item>
</root>

[
  {
    "title": {
      "text": "Chrome"
    },
    "label": {
      "name": "New!",
      "color": "#ff2015"
    },
    "description": "40327 visits"
  },
  {
    "title": {
      "text": "Safari"
    },
    "description": "11577 visits"
  },
  {
    "title": {
      "text": "Firefox"
    },
    "description": "10296 visits"
  },
  {
    "title": {
      "text": "Internet Explorer"
    },
    "description": "3587 visits"
  },
  {
    "title": {
      "text": "Opera"
    },
    "description": "499 visits"
  }
]

Map

The Map widget provides a way to display geographical locations as points on a map. Each Map widget is configured for a particular region of the world, include the entire world map. Points that are located outside the bounds of the chosen region will simply be ignored.

Locations may be specified as latitude/longitude pairs, city names, hostnames or IP addresses.

Supported Sizes

2 x 2
3 x 3
4 x 2
4 x 3
4 x 4

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <points>
    <point>
      <city>
        <city_name>London</city_name>
        <country_code>GB</country_code>
      </city>
      <size>10</size>
    </point>
    <point>
      <city>
        <city_name>San Francisco</city_name>
        <country_code>US</country_code>
        <region_code>CA</region_code>
      </city>
    </point>
    <point>
      <latitude>51.526263</latitude>
      <longitude>-0.092429</longitude>
      <color>d8f709</color>
    </point>
    <point>
      <latitude>-33.94336</latitude>
      <longitude>18.896484</longitude>
    </point>
    <point>
      <host>geckoboard.com</host>
    </point>
    <point>
      <ip>178.125.193.227</ip>
    </point>
  </points>
</root>

{
  "points": {
    "point": [
      {
        "city": {
          "city_name": "London",
          "country_code": "GB"
        },
        "size": 10
      },
      {
        "city": {
          "city_name": "San Francisco",
          "country_code": "US",
          "region_code": "CA"
        }
      },
      {
        "latitude": "22.2670",
        "longitude": "114.1880",
        "color": "d8f709"
      },
      {
        "latitude": "-33.94336",
        "longitude": "18.896484",
        "size": 5
      },
      {
        "host": "geckoboard.com",
        "color": "77dd77",
        "size": 6
      },
      {
        "ip": "178.125.193.227"
      }
    ]
  }
}

Parameters

Inside the points section, the point parameter may take one of the four different forms below.

City name and region

In order to specify the location of a particular city, it must be identified by its name and country. Optionally, the region it belongs to, such as a US state, may also be specified, in order to resolve ambiguities.

The city_name parameter is a string representing the common name for the city, such as "San Francisco". The country_code parameter must be a string containing the two-letter ISO 3166 code for the country that the city belongs to, such as "US" for the United States. A table listing all valid country codes is available on Wikipedia, under the "Code" column.

In addition, a region_code string parameter may optionally be specified, containing a two-letter representation of the region that the city belongs to. This can be used to distinguish between two or more identically named cities in the same country.

If the city is in the United States, region_code (if given) must be a valid ISO 3166-2 code, such as "CA" for California. A full list of ISO 3166-2 codes for the USA is available on Wikipedia.

If the city is not in the United States, the two-letter FIPS region code should be used instead, such as "P5" for the City of Westminster, London. A full list of FIPS region codes, broken up by countries, is available on Wikipedia.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <points>
    <point>
      <city>
        <city_name>San Francisco</city_name>
        <country_code>US</country_code>
        <region_code>CA</region_code>
      </city>
    </point>
  </points>
</root>

{
  "points": {
    "point": [{
      "city": {
        "city_name": "San Francisco",
        "country_code": "US",
        "region_code": "CA"
      }
    }]
  }
}

Latitude and Longitude

The location of the point may also be specified as a latitude / longitude pair. Both values can be given as either numbers(e.g.JSON floating point numerals) or strings containing a number.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <points>
    <point>
      <latitude>37.7577</latitude>
      <longitude>-122.4376</longitude>
    </point>
  </points>
</root>

{
  "points": {
    "point": [
      {
        "latitude": 37.7577,
        "longitude": "-122.4376"
      }
    ]
  }
}

Host

A hostname may also be specified, using the host string parameter. Geckoboard will attempt to locate its geographical position and display it on the map.

{
  "points": {
    "point": [
      {
        "host": "geckoboard.com"
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <points>
    <point>
      <host>geckoboard.com</host>
    </point>
  </points>
</root>

IP Address

An IP address may also be specified using the ip string parameter. This may be useful, for example, when building a Map widget to plot the location of current visitors to a particular website, using the IP address that they're connecting from.

{
  "points": {
    "point": [
      {
        "ip": "207.97.227.239"
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <points>
    <point>
      <ip>207.97.227.239</ip>
    </point>
  </points>
</root>

Additional Parameters

size optional: Each point on the map can have a different size, which is represented as a smaller or larger circle. The minimum size for a point is 1, and the maximum is 10. By default, each point has size 3, but a different value can be specified using the numeric parameter size.

color optional: It is also possible to specify a different colour for each point on the map, by setting the optional color string parameter to the desired hexadecimal colour value.

{
  "points": {
    "point": [
      {
        "city": {
          "city_name": "San Francisco",
          "country_code": "US"
        },
        "size": 2,
        "color": "d8f709"
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <points>
    <point>
      <city>
        <city_name>San Francisco</city_name>
        <country_code>US</country_code>
      </city>
      <size>2</size>
      <color>d8f709 </color>
    </point>
  </points>
</root>

Monitoring

Monitoring widget

The Monitoring widget is used to display whether a particular resource or service (such as your company website) is currently reachable.

It consists of a colour-coded Up/Down arrow, as well as additional (optional) fields for the service's response time and when the most recent downtime occurred.

Supported Sizes

1 x 1
2 x 2

Parameters

status: A string parameter indicating whether the service is up or down. If the value is Up (or any case-insensitive combination thereof), the text will be coloured green, and an upward-pointing arrow will be displayed. If the value is Down, the text will be red, and a downward-pointing arrow will be displayed. If the value is Unreported, the text will be white, and no arrow will be displayed.

downTime: optional A string indicating when the last downtime happened. If status is Down, then this value will be ignored, and displayed as NOW. Omitting this value will display a hyphen in its place.

responseTime: optional A string indicating the current response time for the service. Omitting this value will display a hyphen in its place.

{
  "status": "Up",
  "downTime": "9 days ago",
  "responseTime": "593 ms"
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <status>Up</status>
  <downTime>9 days ago</downTime>
  <responseTime>593 ms</responseTime>
</root>

Down Example

This is an example of a monitoring widget in the "Down" state. The values of the downTime and responseTime parameters are ignored, and "NOW" and "N/A" is displayed, respectively.

Monitoring down example

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <status>Down</status>
  <downTime>2 days ago</downTime>
  <responseTime>593 ms</responseTime>
</root>

{
  "status": "Down",
  "downTime": "2 days ago",
  "responseTime": "593 ms"
}

Number and Secondary Stat

The Number and Secondary Stat visualisation is focused on the display of a metric that can be represented by a single number, along with associated secondary metrics, such as a change or trend indication.

Use this visualisation when the number is the most important aspect of the metric you're trying to display, such as today's sales, or yesterday's website uniques. The secondary statistic can then be used to give context to the current value.

Supported Sizes

1 x 1
2 x 2

Parameters

item

The item parameter is an array, where the first element represents the primary metric to display, and the second, optional, element represents the secondary comparison metric. If the latter is an array of numbers, it is interpreted as a trendline. If it's an object, then it should contain the same parameters as the primary metric, described as follows.

value: For the first item section, this parameter describes the primary metric and should be a number. For the second item section (comparative display) this shows the comparison value. The primary number is formatted according to the usual formatting rules.

text optional: For a 2 x 2 widget you can show a label next to the primary value. For a 1 x 1 if you exclude a number from the second item you can specify a text label instead.

prefix optional: If the number you wish to display has units then you can set a prefix value. This can be a currency symbol such as $, £ or €. The visualisation will automatically convert a prefix of % to a suffix.

type optional: As well as a number, you can also display other number-like metrics. Possible values are time_duration and text.

time_duration displays a time duration instead of a number for both the primary and the secondary values, by interpreting the numeric value as the number of milliseconds in the time period.

For example, 565000 (ms) would be displayed as 9m 25s (9 minutes 25 seconds).

text displays the primary metric as text instead of a number. This is useful, for example, when you would like to display a value with a custom unit.

type

Set this parameter's value to "reverse" to flip the colours of the up/down arrow on the comparison metric so that up is red and down is green. See the Reverse Example below.

absolute

If you're using the comparative option, setting the optional absolute parameter to true will mean the difference is displayed as an absolute value rather than a percentage. This is useful if the comparative value itself is useful for people to know about. For example, displaying units shipped today vs yesterday as absolute values gives you a good indicator of the extra number of units you need to purchase to refill the stock.

Goals

You can add an optional goal from the Set up Widget screen in the app. Adding a goal will replace any other secondary stat that you provide.

Number widget with a goal

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <value>5723</value>
    <text>Total paying customers</text>
  </item>
</root>

{
  "item": [
    {
      "value": 5723,
      "text": "Total paying customers"
    }
  ]
}

Comparison Example

This example shows a simple number widget with a secondary metric that the primary value is compared to. The comparison is displayed as a percentage and colour-coded according to whether the primary metric is an increase or a decrease over the secondary metric.

Set the type parameter to "reverse", as described above, to invert red and green.

Number widget comparison example

{
  "item": [
    {
      "value": 142
    },
    {
      "value": 200
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <value>142</value>
    <text></text>
  </item>
  <item>
    <value>200</value>
    <text></text>
  </item>
</root>

Trendline Example

This example shows a number widget with a secondary metric containing an array of numbers, which is displayed as a trendline below.

Number widget trendline example

{
  "item": [
    {
      "value": "274057"
    },
    [
      "38594",
      "39957",
      "35316",
      "35913",
      "36668",
      "45660",
      "41949"
    ]
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <value>274057</value>
  </item>
  <item>
    <value>38594</value>
    <value>39957</value>
    <value>35316</value>
    <value>35913</value>
    <value>36668</value>
    <value>45660</value>
    <value>41949</value>
  </item>
</root>

Absolute Example

This example shows the behaviour of the secondary (comparative) metric for number widgets where the absolute parameter is set to true.

Number absolute example

{
  "absolute": true,
  "item": [
    {
      "text": "",
      "value": 123
    },
    {
      "text": "",
      "value": 238
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <absolute>true</absolute>
  <item>
    <value>123</value>
    <text></text>
  </item>
  <item>
    <value>238</value>
    <text></text>
  </item>
</root>

Prefix Example

This is an example of a number widget where the prefix parameter for the primary metric is set to a currency symbol, which is used to express the unit of the specific numeric value.

Note that for XML widgets, certain currency symbols must be HTML-escaped and wrapped in a CDATA tag.

Prefix example

{
  "item": [
    {
      "text": "Revenue yesterday",
      "value": 123,
      "prefix": "€"
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <value>123</value>
    <text>Revenue yesterday</text>
    <prefix><![CDATA[&euro;]]></prefix>
  </item>
</root>

Reverse Example

This example shows how the colours of the Up/Down arrow are flipped, so that Up is red (negative) and Down is green (positive). This is helpful, for example, when you are measuring costs, where a lower cost would be desired.

Number reverse example

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <reverse>true</reverse>
  <item>
    <value>565</value>
    <text></text>
  </item>
  <item>
    <value>559</value>
    <text></text>
  </item>
</root>

{
    "type": "reverse",
    "item": [
        {
            "value": 565
        },
        {
            "value": 559
        }
    ]
}

Pie Chart

The Pie Chart widget provides a way to segment a total quantity, and show the relative proportions of each segment of the data set.

An example of a pie chart might be to display the proportion of total users visiting a website for each web browser.

Supported Sizes

1 x 1
2 x 2

Parameters

value: The value parameter can be a number or numeric string representing the proportion of the pie occupied by the slice.

label: The label string parameter will populate the legend for the slice.

color optional: The color string parameter defines the colour of the pie chart slice. It must be given as a hexadecimal colour code, such as d8f709. If provided, the last two hex digits represent the colour transparency: d8f709aa would display the colour d8f709 with a transparency value of aa.

{
  "item": [
    {
      "value": 100,
      "label": "May",
      "color": "13699c"
    },
    {
      "value": 160,
      "label": "June",
      "color": "198acd"
    },
    {
      "value": 300,
      "label": "July",
      "color": "60b8ec"
    },
    {
      "value": 140,
      "label": "August",
      "color": "a4d7f4"
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <value>100</value>
    <label>May</label>
    <color>13699c</color>
  </item>
  <item>
    <value>160</value>
    <label>June</label>
    <color>198acd</color>
  </item>
  <item>
    <value>300</value>
    <label>July</label>
    <color>60b8ec</color>
  </item>
  <item>
    <value>140</value>
    <label>August</label>
    <color>a4d7f4</color>
  </item>
</root>

RAG

RAG widget RAG with column widget

The RAG (Red Amber Green) visualisation offers a traffic light view of your data, which is useful when you have two or three figures you wish to compare at a glance.

It would be ideally suited to displaying, for example, the totals of unpaid, paid and pending invoices from your accounting system.

Geckoboard provides two distinct custom widget types for this visualisation:

The RAG number widgets display three colour-coded numeric values, along with a textual label.
The RAG column and number widget is functionally identical to the RAG number widget, except for an added, colour-coded column which allows you to see how your values are related proportionally. This would be great for tracking your progress through a task list, or for displaying the number of support tickets and their statuses/priorities.

Supported Sizes

1 x 1
2 x 2

Parameters

The RAG widget expects 2 or 3 items. The order of these will determine which colour is applied. The first item being red, the second amber and the third green.

text: A label to indicate what the value represents.

value optional: A number representing the quantity or proportion of the entity being represented. If you omit a value then the corresponding column will not be displayed. This would be useful if you only want to display red and green indicators. If you omit the value for all items then a blank widget will be displayed.

prefix optional: A prefix for the value. This would be ideal for displaying a currency symbol when the value is monetary.

type optional: The type parameter accepts one value reverse. If supplied then the order of the items will be reversed.

{
  "item": [
    {
      "value": 16,
      "text": "Long past due"
    },
    {
      "value": 64,
      "text": "Overdue"
    },
    {
      "value": 32,
      "text": "Due"
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <value>16</value>
    <text>Long past due</text>
  </item>
  <item>
    <value>64</value>
    <text>Overdue</text>
  </item>
  <item>
    <value>32</value>
    <text>Due</text>
  </item>
</root>

Text

Text widget

The Text widget can display up to 10 pages of textual content, which can either be plain text or a subset of HTML.

Supported Sizes

1 x 1
1 x 2
2 x 1
2 x 2
full-width

Parameters

A maximum of 10 item objects may be provided. Each of them specifies the text and, optionally, the type of each page.

text

The text attribute accepts any encoding and may optionally be enhanced with a limited set of HTML tags.

type

The optional type parameter can be used to add extra visual clue to each page of the text widget.

When it's not given or set to 0, no icon will be added.

When type is set to 1 (alert) an exclamation point on yellow background will appear in the top right corner. See the Type 1 Example below.

When type is set to 2 (info), an 'i' icon on grey background will be displayed in the top right corner. See the Type 2 Example below.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <text><![CDATA["Unfortunately, as you probably already know, people"]]></text>
    <type>0</type>
  </item>
  <item>
    <text><![CDATA["As you might know, I am a full time Internet"]]></text>
    <type>1</type>
  </item>
</root>

{
  "item": [
    {
      "text": "In warm regions of the world the arrival of a gecko in your home is seen as good luck.",
      "type": 0
    },
    {
      "text": "Geckos can climb vertical surfaces due to their highly specialized toe pads.",
      "type": 1
    }
  ]
}

Type 1 Example

This example shows a text widget where the page currently being displayed has a type value of 1 (alert).

The yellow exclamation mark in the top-right corner may be used to alert viewers of the dashboard that this particular page of the widget is worth paying attention to.

For example, a text widget displaying the status of your company's servers may set type to 1 when an outage is currently in progress.

Type 1 text widget

{
  "item": [
    {
      "text": "production-web-1: NOT RESPONDING",
      "type": 1
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <text><![CDATA["production-web-1: NOT RESPONDING"]]></text>
    <type>1</type>
  </item>
</root>

Type 2 Example

This example shows a text widget where the page currently being displayed has a type value of 2 (info).

The grey "i" icon in the top-right corner may be used to highlight this page of the widget in particular.

For example, a text widget displaying the state of a shared to-do list may set type to 2 when certain items are due soon and require action.

Type 2 text widget

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item>
    <text><![CDATA["3 to-do items are due next week"]]></text>
    <type>2</type>
  </item>
</root>

{
  "item": [
    {
      "text": "3 to-do items are due next week",
      "type": 2
    }
  ]
}

Polling

Polling Overview

Using a custom widget in polling mode requires you to have an endpoint that exposes data in the correct format. Geckoboard then polls that URL and displays the data in the widget.

Configuration

This section goes into a bit more detail about the custom widget configuration screen.

API Key

If you specify an API key it will be sent as the username for HTTP basic auth in the request. The password will be set to “X”.

Request Parameters

Geckoboard appends some parameters (if this is a POST they will go in the body, if this is a GET then they will go on the URL) to allow the information being returned to be customised.

Format

The format, either XML or JSON, that the response from your script should produce.

Values: either ‘1’ (if the widget is configured for XML) or ‘2’ (if the widget is configured for JSON).

Type

The widget type that the data is formatted for.

Values: Numeric values 1-16 depending on the widget type chosen during widget configuration.

1: Number + optional secondary stat
2: RAG column and numbers
3: RAG numbers only
4: Text
5: Piechart
6: Linechart
7: Geck-o-meter
8: Funnelchart
9: Bulletgraph
10: Highchart
11: Map
12: Monitoring
13: List
16: Leaderboard

Response Formats

If authentication is successful, a HTTP status code of 200 OK should be returned.

In all other cases, your server should return a status code of 403, 404 or 500 (whichever is most appropriate), along with a description of the error.

For example, the following XML payload may be returned along with a status of 403 Forbidden.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <error>Access denied.</error>
</root>

Known Limitations

There is a 10 second timeout. If we don't receive a response within 10 seconds while polling your endpoints, the widget will timeout with the following message:

Error received when loading widget data: 

Errno::ETIMEDOUT

Push

Push Overview

Unlike Polling widgets, whereby data has to be exposed for Geckoboard to poll, the Push API allows data to be pushed directly to widgets instead.

The Push API uses JSON exclusively. XML is not supported.

We’re using WebSockets to update the widgets in real time. You will need a modern browser or Adobe Flash installed to make this work.

Please note that the size of the file that is pushed can not exceed 1 MB.

Details

First of all, you will need a to create a new custom widget to display your data. Go to Geckoboard and create a new custom widget. You should see the following option:

Selecting ‘PUSH’ here will give you a number of different options which you can use to push data to your widget.

Pushing to your widget

To push data to your widget all you need to do is a POST with the correct payload to the URL specified in the widget config.

The payload should be in the following format (this example is for a Number & Secondary Stat widget):

{
  "api_key": "222f66ab58130a8ece8ccd7be57f12e2",
  "data": {
     "item": [
        { "text": "Visitors", "value": 4223 },
        { "text": "", "value": 238 }
      ]
  }
}

You can find your API key on your account page.

The URL you need to POST to is:

https://push.geckoboard.com/v1/send/<widget_key>

This is available in the widget config along with the widget key.

The data must be in the format required by the custom widget you have chosen. See Widget Types for the required format.

Errors

API errors will result in an HTTP response with a suitable status code and the following JSON response:

{
  "message": "Informative error message"
}

Below are some of the possible error conditions, along with their status code:

Error	HTTP Status Code
Response body is empty or invalid JSON	400
You are not authorized to push to this widget	401
Widget does not support push	403
Your API key is invalid	403
The widget does not exist	404
The request body is too large	413
You have exceeded your rate limit	429

Please note that invalid widget data, such as missing required fields, incorrect number formatting, etc. will still result in a 200 OK response from the Push API. Please check the dashboard containing the widget you are pushing to in order to see any validation errors that may have occurred.

Rate Limiting

There is basic rate limiting on the API. This restricts you to 12,000 requests in a 60-minute period for your account. Please get in contact if you’d like to discuss increasing this limit.

If you exceed your rate then the API will return a 429 status and the following error message:

{
  "error":"Rate limit exceeded"
}

Curl Example

Here’s a quick example of how to push some data via 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"