Geckoboard Visit Geckoboard.com

API Reference Node.js

Schemas and types

Your schema is a group of fields which define your data types.

The Datasets API currently supports the following types:

Number format

number fields can be optional.

Example creation

"fields":{
  "amount":{
    "type": "number",
    "name": "Amount",
    "optional": true
  }
}

Date format

date types must be formatted as YYYY-MM-DD.

Example creation

"fields":{
  "date":{
    "type": "date",
    "name": "Date"
  }
}

Example adding data

"data":[
  {
    "date": "2016-01-01"
  }
]

Datetime format

datetime fields must be formatted as ISO 8601 strings. We recommend you use the YYYY-MM-DDThh:mm:ssTZD variation, which will produce values that look like 2016-07-03T16:30:00Z.

Example creation

"fields":{
  "datetime":{
    "type": "datetime",
    "name": "Datetime"
  }
}

Example adding data

"data":[
  {
    "datetime": "2016-01-01T12:00:30Z"
  }
]

String format

string fields must not contain more than 100 characters.

Example creation

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

Example adding data

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

Percentage format

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.

Example creation

"fields":{
  "percentage":{
    "type": "percentage",
    "name": "Percentage",
    "optional": true
  }
}

Example adding data

"data":[
  {
    "percentage": 0.35
  }
]

Money format

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 that the currency code should be in uppercase.

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

A money field can be optional.

Example creation

"fields":{
  "dollars":{
    "type": "money",
    "name": "Dollars",
    "currency_code": "USD",
    "optional": true
  }
}

Example adding data

"data":[
  {
    "dollars": 14000
  }
]

Update frequency

Widgets powered by datasets update every 5 minutes. In the future, we’re planning to make improvements so that they can update as soon as new data is received.

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 status and the following error message:

{
  "error": {
    "message": "You have exceeded the API rate limit of 60 requests per minute. Try sending data less frequently"
  }
}

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 fields per dataset

A dataset can contain up to 10 fields, with any combination of types.

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.

We’ll be adjusting these limits as we continue to improve the feature. If you have any questions or suggestions please contact our Customer Success team.

Exporting data from Geckoboard

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.

Require node library

const gb = require('geckoboard')(apiKey)

Note You can find your API key by logging into the Geckoboard application and visiting the Account section.

Ping to authenticate

gb.ping(callback)

Verify that your API key is valid and that you can reach the Geckoboard API.

Find or create

gb.datasets.findOrCreate(options, callback)

Verify an existing dataset or create a new one. unique_by is an optional array of one or more field names whose values will be unique across all your records.

{
  "id": "sales.gross",
  "fields": {
    "amount": { "type": "number", "name": "Amount", "optional": false },
    "timestamp": { "type": "datetime", "name": "Time" }
  },
  "unique_by": ["timestamp"]
}

Delete

gb.datasets.delete(id, callback)

Delete the dataset and all data with the given id

Dataset

Used to manipulate the data in a dataset. An instance of which is received through the callback in findOrCreate

Put

dataset.put(items, callback)

Replaces all data in the dataset

[
  { timestamp: '2016-01-01T12:00:00Z', amount: 8192 },
  { timestamp: '2016-01-02T12:00:00Z', amount: 4096 },
  { timestamp: '2016-01-03T12:00:00Z', amount: 16384 }
]

Post

dataset.post(items, options, callback)

Appends data to a dataset.

Should the number of records in your dataset exceed the limit following a post old records will be discarded.

[
  { timestamp: '2016-01-01T12:00:00Z', amount: 8192 },
  { timestamp: '2016-01-02T12:00:00Z', amount: 4096 },
  { timestamp: '2016-01-03T12:00:00Z', amount: 16384 }
]
{ delete_by: 'timestamp' }

Delete

dataset.delete(callback)

Deletes the dataset and all data therein