Geckoboard Visit Geckoboard.com

API Reference Python

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.

Getting started

Install the python client from PIP

pip install geckoboard.py

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

import geckoboard

client = geckbooard.client(API_KEY)

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

Authentication

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

client.ping()

Example:

client('good-api-key').ping() # => true
client('bad-api-key').ping() # => raises Exception

Finding or creating a dataset

Find and verify an existing dataset or create a new dataset with the find_or_create method. unique_by is an optional list of one or more field names whose values will be unique across all your records.

client.datasets.find_or_create(dataset_id, fields, unique_by)

Params:

Example:

dataset = client.datasets.find_or_create('sales.by_night', {
  'amount': { 'type': 'number', 'name': 'Amount', 'optional': False },
  'timestamp': { 'type': 'datetime', 'name': 'Time' }
}, ['timestamp'])

The full list of available field types is described at the top of this page.

Replacing all data in a dataset

Replace all data in the dataset by calling the put method.

dataset.put(items)

Params:

Example:

dataset.put([
  { 'timestamp': '2016-01-01T12:00:00Z', 'amount': 819 },
  { 'timestamp': '2016-01-02T12:00:00Z', 'amount': 409 },
  { 'timestamp': '2016-01-03T12:00:00Z', 'amount': 164 }
])

Appending data to a dataset

Append records to a dataset by calling the post method.

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

dataset.post(items, delete_by)

Params:

Example:

dataset.post([
  { 'timestamp': '2016-01-03T12:00:00Z', 'amount': 312 },
  { 'timestamp': '2016-01-04T12:00:00Z', 'amount': 665 },
  { 'timestamp': '2016-01-05T12:00:00Z', 'amount': 453 }
], 'timestamp')

Deleting a dataset

Delete the dataset and all data with the given id.

client.datasets.delete(dataset_id)

Params:

Example:

client.datasets.delete('sales.gross') # => true

You can also delete a dataset by calling the delete method on a dataset.

dataset = client.datasets.find_or_create(...)
dataset.delete() # => true

Language support

We officially support Python versions > 2.7.6