A simple, powerful way to access your most important data with Geckoboard.

Welcome

Welcome to Geckoboard's Datasets API – a simple yet highly flexible way of building live TV dashboards from data in third-party tools, databases and in-house systems.

You can view code examples in the area to the right, and you can switch the programming language of the examples with the tabs in the top right. We provide examples in cURL, Node.js, Ruby, and Python, but you can use any programming language of your choice.

Looking for quickstart guides? Head over to the Walkthroughs section.
Geckoboard Developer Community
Visit our Developer Community to learn more about how to unlock our robust API and how to create apps to add the data that you need to power your dashboards. Get involved sharing your projects and repos!
Looking for Custom Widgets? Head over to the Legacy docs. However, we encourage you to try Datasets for the most simple, powerful way to access your most important data with Geckoboard.

Before you start

What is a dataset?

Datasets are best thought of as tables. Here’s an example:

Productstring

Unit costmoney (USD)

Salesnumber

Profit marginpercentage

Shipping datedate

Papayas

$9

800K

55%

2018-03-07

Mangos

$6.60

300K

48%

2018-03-14

Pineapples

$5.60

250K

44%

2016-03-21

Your dataset’s schema defines the columns of this table to let Geckoboard know what form your data takes. You can include up to 10 different fields in a dataset, so one dataset can easily power a whole dashboard.

A well thought-through schema will make it much easier to configure your widgets when it comes to adding them to your Geckoboard dashboard.

It’s important to note the relationship between the way you are able to visualize the dataset and the schema it uses.

When you’re adding a dataset widget to your dashboard, we’ll look at your schema and present the 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.

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.
It’s currently not possible to combine data from two or more datasets to build a visualization. Visualizations are powered by individual datasets.

Though we don't provide in-house development services, please ask about our partnership with Saasler, who can build datasets out of your data. For more information and pricing, download the PDF (3.8MB).

For a guide to the terms used in this reference, head over to the Glossary section.

API Calls

Require node library:

constgb=require("geckoboard")(apiKey);

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

gem'geckoboard-ruby'

And then execute:

$bundle

Or install it yourself as:

$geminstallgeckoboard-ruby

Require the gem and create an instance of the client:

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

Install the python client from PIP:

pipinstallgeckoboard.py

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

importgeckoboardclient=geckoboard.client(API_KEY)

An API call is a specifically formatted HTTP request to a web server, which will answer the request with an HTTP response.

The Datasets API only accepts secure connections, so you must make all requests over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authenticate your account when using the API by including your personal API key, followed by a colon :, in the request.

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

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

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

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

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.
If you’re having problems with authentication get in contact with our Customer Success team who will gladly help you.

If you haven’t included a unique_by array with your dataset definition, then all new records will be appended to the existing contents of your dataset. If you have included a unique_by array of fields, then any conflict between your new and existing records will be resolved by merging your updates into the contents of your dataset. This can be used to modify existing records in case their values have changed since your last update.

Schemas and types

Schema formatting and visualization types

Your schema will determine 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 are after a particular visualization.

To add “today” as a filter for your visualization, you’ll need to use datetime (as opposed to date) as data type.

Number

Number:money OR number OR percentageNumber with sparkline comparison:money OR number OR percentageNumber with specific time-based sparkline comparison:money OR number OR percentage AND date OR datetimeNumber with percentage comparison:money OR number OR percentageNumber with number comparison:money OR number OR percentageNumber with goal comparison:money OR number OR percentage

Geck-O-Meter

Geck-O-Meter:money OR number OR percentageGeck-O-Meter with needle on specific time-based value:money OR number OR percentage AND date OR datetime

Line Chart

Line Chart Series:money OR number OR percentageLine Chart X-Axis:date OR datetime

There are two ways to create multi-series line chart. When creating a multi-series line chart, you’ll need to pick one:

Having Line Chart Series with identical data types (i.e. all of them money)

Having a string value in the dataset to “split by” (which automatically generates series for each different string value)

Column Chart

Column Chart Metric:money OR number OR percentageColumn Chart X-Axis:date OR datetime OR string

Bar Chart

Bar Chart Metric:money OR number OR percentageBar Chart X-Axis:date OR datetime OR string

Leaderboard

Leaderboard Label:stringLeaderboard Value:money OR number OR percentage

Table

Raw Table: Any data type as long as there are at least two of them.Summary Table:money OR number OR percentage (for columns) AND date OR datetime OR string (for grouping)

money fields represent a certain amount of money in a single currency. You can specify the currency when defining the field using the currency_code option. This option accepts three character currency codes defined by the ISO 4217 standard.

Note: Currency codes should always be in uppercase.

Records should specify the amount of money in the currency’s smallest denomination, as an integer. For example, the USD’s smallest denomination is the cent, so a USD field would specify $10.00 as 1000.

When using a percentage field, a number in the 0 to 1 range will be displayed in the 0 to 100% range.

For example, a percentage field with value 0.35 will be interpreted by Geckoboard as the percentage 35%.

Values above 1 will correspond to percentages higher than 100%. For example, 1.5 will be interpreted as 150%.

A percentage field can be optional.

String format

Example creation:

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

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

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

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

Example adding data:

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

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

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

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

All string fields must not contain more than 100 characters.

Tip: If you're receiving the error post Error: Field "[field_name]" may not contain more than 100 characters despite no entries exceeding the character limit, you may be using double- or triple-byte characters. Some non-latin languages need two or more bytes for representing more complex characters. Consider using a lower character limit or truncating instances of double- or triple-byte characters.

Update frequency

Widgets powered by datasets update in real-time when new data is received.

There's no limitation on the frequency that you can send an update to a dataset, as long as it falls within the rate limit below, but be aware that the visualizations on your dashboards will only show changes up to every 10 seconds. We would therefore recommend not to update a dataset more frequently than this.

Rate Limiting

There is basic rate limiting on the API. This restricts you to 60 requests per minute for your API key.

If you exceed your limit, the API will return a 429 TOO MANY REQUESTS status and the following error message 👉

Dataset limits

We’ve designed datasets with flexibility in mind. In many cases, a whole dashboard of different visualisations may be powered from a single dataset.

Remember that Geckoboard is a data visualisation tool, not an analysis tool or data warehouse. Please don’t use Geckoboard as your primary data store.

Number of records per dataset

Each dataset can contain up to 5000 records.

When a dataset exceeds the record count limit the oldest records (by insertion time) will be removed. This behaviour can be overridden by using the delete_by option when appending new records.

When set to the name of a date or datetime field, the delete_by option will be used to order your records (from newest to oldest) before records are truncated from the dataset.

If you specify a date field for delete_by then the datasets API will try to avoid leaving your dataset with a partially complete day’s worth of data. When it deletes a record it will also delete any records that have the same date value for that field.

If the delete_by field is a datetime field then only records with that exact same timestamp (i.e. same year, month, day, hour, minute, second, and millisecond) will be deleted.

Records per request

Each PUT or POST request will accept 500 records, which includes both new records and updates to existing records.

Number of datasets per account

Each Geckoboard account is limited to 100 datasets. When the number of datasets is reached, no more datasets can be added. You can delete datasets via the API.

Exporting your data

The purpose of the datasets API is to enable you to get the data you need onto your dashboard. With this in mind, we don’t provide support for exporting the data in your datasets.

If you intend to use the data you send to Geckoboard for other purposes, please ensure you also send it to an appropriate data store.

Glossary of terms

API key

An authorization code used to identify you as the requester.

Authentication

Used to identify you as the user of the API.

Field

A 'column' in spreadsheet terms. Structural, rather than referring to actual data. Has (at minimum) a name and a type.

Get

The HTTP method for retrieving resources from the Datasets API.

Name

The developer-friendly designation that is used as a unique identifier for both either a data set or field. URL-friendly.

Post

The HTTP method for creating resources with the Datasets API.

Put

The HTTP method for updating resources with the Datasets API.

Rate limiting

Limits the consumption of the Datasets API to a certain number of requests per period of time (set as 60 requests per minute for your API key).

Record

A 'row' in spreadsheet terms. A single collection of data that fit into the data set’s structure.

Schema

The defined structure of a dataset (a group of fields).

Type

Required when defining a field. Tells Geckoboard and the user what sort of data is expected in a field.

Walkthroughs

How to create a dataset

For instructions and code blocks, set your language to cURL or Node.js. 👆

For instructions and code blocks, set your language to cURL or Node.js. 👆

Follow this guide to add your first Dataset to Geckoboard using cURL.

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

For instructions and code blocks, set your language to cURL or Node.js. 👆

For instructions and code blocks, set your language to cURL or Node.js. 👆

Step 1: Installation

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

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

npminstallgeckoboard

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.

Windows users can access the Command Prompt by right-clicking Start and choosing Command Prompt from the Quick Link menu.

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

Step 2: Authenticate your account

Test whether your API key is working by pasting this command to your terminal. Replace your-api-key with your API key.
If you missed including the : or are still asked for a password, simply hit the Enter key on your terminal.

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

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

If authentication is successful {} should be logged to your console.
Find your API key 🔑 by logging into your Geckoboard account and following these steps:

Click your initials in the top right corner and select Account.

On the Account Details screen, scroll down and look for API Key towards the bottom of the page.

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.
If you’re having problems with authentication then you can get in contact with our Customer Success team who can assist you.

Step 3: Make a dataset

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

Where PUT is the HTTP method that will allow us to create the Dataset and :id is a string to help you identify your dataset from within the application.

Add the data with dataset.put as per the example below. Replace your-api-key with your API key:

varAPI_KEY="your-api-key";vargb=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

To update a dataset, you need to make a request with the data you wish to store.

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.

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.

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.

You can find more detailed information in the API Reference section. Make sure your language is set to Node.js.

Send SQL data to datasets

SQL-Dataset is a command line app that quickly and easily integrates your Microsoft SQL Server, MySQL, Postgres and SQLite databases with Geckoboard. Rather than having to work with client libraries and write code to connect to and query your database, with SQL-Dataset all you need to do is fill out a simple config file and run the program from the command line.