Geckoboard Visit Geckoboard.com

API Reference curl

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.

Authentication

The Datasets API only accepts secure connections. So you must make all requests over HTTPS.

You can test your API key is working with the following cURL command (just replace the made up key with your own).

curl https://api.geckoboard.com/ -u "222efc82e7933138077b1c2554439e15:"

Response

You should get a 200 response containing {}

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

Creating a new dataset

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

Where :id is a string to help you identify your dataset from within the application.

Attributes

Attribute Description
fields An object with keys for each column in your dataset. The value describes the type for that column.
unique_by An optional array of one or more field names whose values will be unique across all your records.

Example

curl https://api.geckoboard.com/datasets/sales.gross \
  -X PUT \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "fields": {
    "amount": {
      "type": "number",
      "name": "Amount",
      "optional": false
    },
    "timestamp": {
      "type": "datetime",
      "name": "Date"
    }
  },
  "unique_by": ["timestamp"]
}'

Response

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

Replace all data in a dataset

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

Attributes

Attribute Description
data An array of objects with key + values representing a record in your dataset

Example

curl https://api.geckoboard.com/datasets/sales.gross/data \
  -X PUT \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": [
    {
      "timestamp": "2016-01-01T12:00:00Z",
      "amount": 819
    },
    {
      "timestamp": "2016-01-02T12:00:00Z",
      "amount": 409
    },
    {
      "timestamp": "2016-01-03T12:00:00Z",
      "amount": 164
    }
  ]
}'

Response

{}

Append data to a dataset

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

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.

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

Attributes

Attribute Description
data An array of objects with key + values representing a record in your dataset
delete_by An optional string specifying the name of a date or datetime field used order records for truncation

Example

curl https://api.geckoboard.com/datasets/sales.gross/data \
  -X POST \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": [
    {
      "timestamp": "2016-01-01T12:00:00Z",
      "amount": 819
    },
    {
      "timestamp": "2016-01-02T12:00:00Z",
      "amount": 409
    },
    {
      "timestamp": "2016-01-03T12:00:00Z",
      "amount": 164
    }
  ]
}'

Response

{}

Delete a dataset

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

Example

curl -X DELETE \
     -u '222efc82e7933138077b1c2554439e15:' \
     https://api.geckoboard.com/datasets/sales.gross

Response

{}