Geckoboard Visit Geckoboard.com

Getting started

Follow this guide to add your first Dataset to Geckoboard

Install the Node module

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

First, create a new directory for your Node app. Now in your terminal, cd to your app’s directory and run:

npm install geckoboard

Authenticate your account

You can find your API key in the Account Section of Geckoboard. Don’t have an account? Create one here

Keep this key secret. Its just as powerful as your login credentials.

Create a file called app.js and add the code below. Replace your-api-key with your API key:

var API_KEY = 'your-api-key';

var gb = require('geckoboard')(API_KEY);

gb.ping(function (err) {
  if (err) {
    console.error(err);
    return;
  }

  console.log('Authentication successful');
});

Run app.js in your terminal:

node app.js

If authentication is successful Authentication successful should be logged to your console.

If you’re having problems with authentication then you can get in contact with our Customer Success team who can assist you.

Make a dataset

You’ll need to give your dataset an id so that you can find it easily in Geckoboard. In this example we’re creating a dataset with the id sales.by_day. Learn more about making datasets

Before you create your first dataset you’ll need to plan your data’s schema. A schema is a collection of fields which will let us know what form your data takes.

Copy the code below into app.js.

var API_KEY = 'your-api-key';

var gb = require('geckoboard')(
  API_KEY
);

gb.datasets.findOrCreate(
  {
    id: 'sales.by_day',
    fields: {
      quantity: {
        type: 'number',
        name: 'Number of sales'
      },
      gross: {
        type: 'money',
        name: 'Gross value of sales',
        currency_code: "USD"
      },
      date: {
        type: 'date',
        name: 'Date'
      }
    }
  },
  function (err, dataset) {
    if (err) {
      console.error(err);
      return;
    }

    console.log('Dataset created');
  }
);

Note If you run this script, Geckoboard will create the dataset schema, but no data has been added to the dataset yet, so you won’t be able to create a widget.

The Datasets API currently supports the following types: date, datetime, number, percentage, string, money. Read more about types

Adding data

To update a dataset, you need to make a request with the data you wish to store. This will replace the existing contents of the dataset.

Each record you send to the dataset must only include the fields that you specified when you first created the dataset. The value supplied for a field must conform to that field’s type. For example, attempting to store a number in a datetime field will result in an error.

Add the data with dataset.put as per the example below.

var API_KEY = 'your-api-key';

var gb = require('geckoboard')(
  API_KEY
);

gb.datasets.findOrCreate(
  {
    id: 'sales.by_day',
    fields: {
      quantity: {
        type: 'number',
        name: 'Number of sales'
      },
      gross: {
        type: 'money',
        name: 'Gross value of sales',
        currency_code: "USD"
      },
      date: {
        type: 'date',
        name: 'Date'
      }
    }
  },
  function (err, dataset) {
    if (err) {
      console.error(err);
      return;
    }

    dataset.put(
      [
        { date: '2016-01-01', quantity: 819, gross: 2457000 },
        { date: '2016-01-02', quantity: 409, gross: 1227000 },
        { date: '2016-01-03', quantity: 164, gross: 492000 }
      ],
      function (err) {
        if (err) {
          console.error(err);
          return;
        }

        console.log('Dataset created and data added');
      }
    );
  }
);

Run your script and build a widget

Run app.js in your terminal:

node app.js

Should anything fail then err should give you some specifics around what went wrong.

Assuming you’ve encountered no error, then that’s it. Congratulations, you’ve created your first dataset!

Now that you’ve created a dataset, go ahead and create a widget. Head to Geckoboard, click ‘Add Widget’, choose ‘Datasets’ as your data source and select your dataset from the list. Of course you can also delete this dataset

You can find more detailed information in the API Reference section.