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.
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.
Selecting ‘PUSH’ here will give you a number of different options which you can use to push data 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 data must be in the format required by the custom widget you have chosen. See Widget Types for the required format.
The payload should be in the following format (this example is for a Number & Secondary Stat widget):
{
"api_key": "YOUR_API_KEY",
"data": {
"item": [
{ "text": "Visitors", "value": 4223 },
{ "text": "", "value": 238 }
]
}
}For Highcharts 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\": {...}"
}
}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.
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.
There is basic rate limiting on the API. This restricts you to 8,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"
}Here’s a quick example of how to push some data via cURL:
curl 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}]}}'Here’s a quick example of how to push some Highcharts data via cURL:
curl https://push.geckoboard.com/v1/send/example-widget-key -d '{"api_key":"example-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]}]}"}}'