community.geckoboard.com

Datasets API Reference

Geckoboard's Datasets API is a powerful and flexible way to compile data from in-house systems, third-party tools, and databases on your dashboard.

To do this you'll need to:

  1. Write a script that connects to your data source and requests the required data.
  2. Create and push a dataset to Geckoboard that includes all the metrics you want to display.

Authentication

Find your API key

Log into your Geckoboard account and follow these steps:

  1. Click your initials in the top right corner and select Account.
  2. On the Account Details screen, scroll down and look for API Key towards the bottom of the page.

Install a client library

Create a new directory for your Node.js app. Then, in your terminal, cd to your app’s directory and run:

npm install geckoboard

To begin, add this line to your application’s Gemfile:

gem 'geckoboard-ruby'

And then execute:

$ bundle

Or install it yourself as:

gem install geckoboard-ruby

Require the gem and create an instance of the client:

require 'geckoboard'
client = Geckoboard.client(api_key)

Install the python client from PIP:

pip install geckoboard.py

Import the Geckoboard package and create an instance of the client using your API key:

import geckoboard

client = geckoboard.client(API_KEY)

You can make calls to the Datasets API with whichever method you usually use to make HTTP requests, but Geckoboard offers client libraries that make interacting with the API even simpler.

Switch the programming language of the examples with the tabs in the top right. By default, the Datasets API Docs demonstrate using cURL to interact with the API over HTTP.

If you're on a Unix based OS (Mac, Linux), you likely have cURL installed on your machine (use the curl -V command in your terminal to confirm). Windows users can access the Command Prompt by searching for Command within Cortana.

We’ll be using the Geckoboard Node.js library to make a simple Node.js app. Node.js version 4+ is required.

Make your first API call

curl https://api.geckoboard.com/ -u "your-api-key:"

You should receive a 200 response containing {}

Ping to authenticate:

import { Geckoboard } from 'geckoboard';

const API_KEY = 'YOUR_API_KEY';

const gb = new Geckoboard(API_KEY);

try {
  await gb.ping()
  console.log("success")
} catch (err) {
  console.log(err);
}

Verify that your API key is valid and that you can reach the Geckoboard API with the #ping method:

client.ping

Example:

Geckoboard.client('good-api-key').ping # => true
Geckoboard.client('bad-api-key').ping # => raises Geckoboard::UnauthorizedError

client.ping()

Example:

client('good-api-key').ping() # => true
client('bad-api-key').ping() # => raises

Authenticate and test your account when using the Datasets API by including your personal API key in the request.

If you missed including the colon : or are still asked for a password, hit Enter in your terminal.

Verify that your API key is valid and that you can reach the Geckoboard API with the ping method.

Plan your schema

When you’re adding a dataset widget to your dashboard, we’ll look at your schema and present the visualization options that make sense for the types of data you’re sending us. For example, to plot a line chart the dataset must contain the date or datetime types.

Visualizations are powered by individual datasets, which means you can't combine data from two or more datasets to build a visualization.

Geckoboard can handle data aggregation and grouping, so there’s no need to pre-aggregate your data. And when an update is received via the API, all the widgets powered by that dataset are then updated automatically.

The Datasets API currently supports the following types:

Date format

Example creation:

"fields":{
  "date":{
    "type": "date",
    "name": "Date"
    "optional": false
  }
}

Example adding data:

"data":[\
  {\
    "date": "2018-01-01"\
  }\
]

All date types must be formatted as YYYY-MM-DD (e.g. 2018-01-01).

For hours, minutes and seconds, use the Datetime format.

A date field can be NULL if set as optional.

Datetime format

Example creation:

"fields":{
  "datetime":{
    "type": "datetime",
    "name": "Datetime"
    "optional": false
  }
}

Example adding data:

"data":[\
  {\
    "datetime": "2018-01-01T12:00:30Z"\
  }\
]

datetime fields must be formatted as ISO 8601 strings, the International Standard for the representation of dates and times.

Duration format

"fields": {
  "name": "Duration",
  "type": "duration",
  "time_unit": "minutes",
  "optional": false
}

Example adding data:

"data":[\
  {\
    "duration": 83\
  }\
]

Money format

Example creation:

"fields":{
  "dollars":{
    "type": "money",
    "name": "Dollars",
    "currency_code": "USD",
    "optional": false
  }
}

Example adding data:

"data":[\
  {\
    "dollars": 14000\
  }\
]

Number format

Example creation:

"fields":{
  "amount":{
    "type": "number",
    "name": "Amount",
    "optional": false
  }
}

Example adding data:

"data":[\
  {\
    "amount": 42\
  }\
]

Percentage format

Example creation:

"fields":{
  "percentage":{
    "type": "percentage",
    "name": "Percentage",
    "optional": false
  }
}

Example adding data:

"data":[\
  {\
    "percentage": 0.35\
  }\
]

String format

Example creation:

"fields":{
  "string":{
    "type": "string",
    "name": "String"
    "optional": false
  }
}

Example adding data:

"data":[\
  {\
    "string": "This is a string field"\
  }\
]

API requests

Find or create a new dataset

PUT https://api.geckoboard.com/datasets/:id

Example:

curl https://api.geckoboard.com/datasets/sales.by_day \
  -X PUT \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "fields": {
    "amount": {
      "type": "number",
      "name": "Amount",
      "optional": false
    },
    "timestamp": {
      "type": "datetime",
      "name": "Date"
    }
  },
  "unique_by": ["timestamp"]
}'

Append data to a dataset

POST https://api.geckoboard.com/datasets/:id/data

Example:

curl https://api.geckoboard.com/datasets/sales.by_day/data \
  -X POST \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": [\
    {\
      "timestamp": "2018-01-01T12:00:00Z",\
      "amount": 819\
    },\
    {\
      "timestamp": "2018-01-02T12:00:00Z",\
      "amount": 409\
    },\
    {\
      "timestamp": "2018-01-03T12:00:00Z",\
      "amount": 164\
    }\
  ]
}'

Replace all data in a dataset

PUT https://api.geckoboard.com/datasets/:id/data

Example:

curl https://api.geckoboard.com/datasets/sales.by_day/data \
  -X PUT \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": [\
    {\
      "timestamp": "2018-01-01T12:00:00Z",\
      "amount": 819\
    },\
    {\
      "timestamp": "2018-01-02T12:00:00Z",\
      "amount": 409\
    },\
    {\
      "timestamp": "2018-01-03T12:00:00Z",\
      "amount": 164\
    }\
  ]
}'

Delete a dataset

DELETE https://api.geckoboard.com/datasets/:id

Example:

curl -X DELETE \
     -u '222efc82e7933138077b1c2554439e15:' \
     https://api.geckoboard.com/datasets/sales.by_day

Limits and quotas

API rate limit

  "error": {
    "message": "You have exceeded the API rate limit of 60 requests per minute. Try sending data less frequently"
  }

Records per dataset

Each dataset can contain up to 5000 records.

Visualization requirements - Your schema determines the visualizations that can be built with your dataset on a Geckoboard dashboard.

Make sure to include these types of data in your schema if you're building a particular visualization.