Authentication – Geckoboard Datasets API

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.

Define 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.

Datatypes supported by the Datasets API

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

Response:

{
  "id": "sales.by_day",
  "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": [] }'

Clear all data in a dataset

Wipes clean all the existing data in a dataset by passing an empty array via the PUT method.

Limits and quotas

API key limits include 60 requests per minute and datasets can contain up to 5000 records.

Visualization requirements

Your schema determines the visualizations that can be built with your dataset on a Geckoboard dashboard. Ensure to include appropriate types of data for the desired visualizations.