Getting started with the Datasets API

Geckoboard’s Datasets API lets you compile data from in-house systems, third-party tools, and databases on a simple dashboard. Instantly accessible via sharing links, mobile, TV screens, it allows developers and team members to get the exact numbers they need – without the headache.

You can access the Datasets API on the command line using cURL or through a client built in whichever language you prefer. We provide walkthroughs for our Node.js, Ruby, and Python clients.

If you think you may need some help integrating with the Datasets API, you can reach out to our Customer Success team.

What is a dataset?

Datasets are best thought of as tables. Your dataset’s schema defines the fields – or 'columns' – of this table to let Geckoboard know what structure your data takes. You can include up to 10 different fields in a dataset, so one dataset can easily power a whole dashboard. Fields have, at minimum, a name and a type.

Here's an example of an dataset:

Product
string
Unit cost
money (USD)
Sales
number
Profit margin
percentage
Shipping date
date

Papayas

$9

800K

55%

2018-03-07

Mangos

$6.60

300K

48%

2018-03-14

Pineapples

$5.60

250K

44%

2016-03-21

The relationship between the way you're able to visualize the dataset and the schema it uses is key. A well thought-through schema will make it much easier to configure your widgets when it comes to adding them to your Geckoboard dashboard.

Read the schema formatting and visualization types section to see which ones are available and how to shape your schema for a particular one.

Install a client library

We provide official libraries for different programming languages.

If you're on a Unix based OS (Mac, Linux), you likely have it installed on your machine. Regardless of the OS you're using, you can check with the curl -V command on your terminal to see if you have it installed.

If you need to install cURL, please visit their download page for instructions.

Tip

Windows users can access the Command Prompt by searching for Command within Cortana.Searching for command within Cortana in Windows

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

First, create a new directory for your Node.js app.

Next, 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

Alternatively, 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)

It's likely that you have python installed on your machine. Here are instructions on how to check based on the OS you're currently using. You'll also find instructions on how to install python in case you don't yet have it.

Install the python client from PIP

pip install geckoboard.py

Important note

These instructions are for code stored in the same directory as the client. The standard import method for packages should be used if app.py is being stored elsewhere.

Authenticate your Geckoboard account

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

What's an API key?

An API key is an authorization code used to identify you as the requester. You can find your Geckoboard API key by following these steps.

Your Geckoboard API key is just as powerful as your login credentials, so keep it safe. Do not share it in publicly accessible areas such GitHub, client-side code, and so forth.

You can test if your API key is working by peplacing your-api-key with your API key. Make sure you keep the colon (:) in the request.

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

You should get a 200 response containing {}

Tip

If you missed including the : or are still asked for a password, simply hit the Enter key on your terminal.

Verify that your API key is valid with the #ping method:

gb.ping(callback);
Attribute Type Required?
  callback Function Yes

Verify that your API key is valid with the ping method:

client.ping

Example

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

Verify that your API key is valid with the ping method:

client.ping()

Example

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

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:

Next step

You're ready to begin creating your first dataset using our walkthroughs for cURL, Node.js, Ruby, and Python.

Was this article helpful?

Awesome! 👍 Thanks so much for your feedback!

Sorry about that! Start a conversation now.

We're ready to help, 24 hours a day, 5 days a week

Get support
  • Fernanda Customer Success Avatar

    Megan

    USA
  • Hariharan Customer Success Avatar

    Hariharan

    India
  • Fernanda Customer Success Avatar

    Yasmin

    Spain
  • Luis Customer Success Avatar

    Luis

    UK
  • Richard Customer Success Avatar

    Richard

    UK
  • Fernanda Customer Success Avatar

    Fernanda

    Brazil
  • Heather Customer Success Avatar

    Heather

    USA