Create a new dataset using Node.js

Follow this guide to add your first Dataset to Geckoboard using Node.js.

Before you start

Node.js is just one of the programming languages you can use to add a Dataset to Geckoboard. We have also have walkthroughs for cURL, Ruby, and Python.

We also have a dedicated guide to sending SQL data to datasets using either a MacOS, Linux or Windows machine or server.

Installation

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.

Now in your terminal, cd to your app’s directory and run:

npm install geckoboard

Authenticate your account

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 {} should be logged to your console.

Note

You can find your API key by following these steps.

Important note

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.

Get help

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.

Copy the code below into app.js. Replace your-api-key with your API key. Should anything fail then err should give you some specifics around what went wrong.

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");
  }
);

Run app.js in your terminal:

node app.js

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. Learn more about making datasets.

The Datasets API currently supports the following types:

  • date
  • datetime
  • number
  • percentage
  • string
  • money

Important note

You must use lower case letters for field names.

Read more about types.

Add data to the dataset for the first time

To add data to the dataset for the first time, you must use the PUT method (which is normally used to replace all data).

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. Replace your-api-key with your API key:

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 app.js in your terminal:

node app.js

Append data to the dataset

You can append records to your dataset by using the POST method. These new records will be added to the existing contents of your datasets.

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

Should the number of records in your dataset exceed the limit following a POST the oldest records (by insertion time) will be removed. This behaviour can be overridden by using the delete_by option when appending new records.

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.post(
      [{ date: "2016-01-04", quantity: 42, gross: 52000 }],
      {},
      function(err) {
        if (err) {
          console.error(err);
          return;
        }

        console.log("Data added");
      }
    );
  }
);

Run app.js in your terminal:

{node app.js

Next steps

Assuming you’ve encountered no errors, then that’s it! You've created a new dataset using Node.js.

You can find more detailed information about configuring your dataset in our API Reference.

You can also find instructions on how to delete this dataset.

Suggested next step

Learn how to create a new widget using your new dataset.

Was this article helpful?

Awesome! 👍  Thanks so much for your feedback!