Create a new dataset using Python

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

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, Node.js, 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

It's likely that you have python installed on your machine. Here are instructions on how to check based on the OS you're currently using. You'll also find instructions on how to install python in case you don't yet have it.

Install the python client from PIP

pip install geckoboard.py

Important note

These instructions are for code stored in the same directory as the client. The standard import method for packages should be used if app.py is being stored elsewhere.

Authenticate your account

Create a file called app.py and add the code below. Replace API_KEY with your API key:

import geckoboard
client = geckoboard.client("API_KEY")

try:
    client.ping()
    print "Authentication successful"

except:
    print "Incorrect API Key"

Run app.py:

python app.py

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

import geckoboard
client = geckoboard.client("API_KEY")

try:
    client.ping()
    print "Authentication successful"

except:
    print "Incorrect API Key"

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

Run app.py:

python app.py

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 API_KEY with your API key:

import geckoboard
client = geckoboard.client(“API_KEY”)

try:
    client.ping()
    print "Authentication successful"

except:
    print "Incorrect API Key"

dataset = client.datasets.find_or_create('sales.by_day', {'amount': { 'type': 'number', 'name': 'Amount', 'optional': False },'timestamp': { 'type': 'datetime', 'name': 'Time' }}, ['timestamp'])
print "Dataset successfully created"

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 }
  ])
print "Data in the dataset has been replaced (or added for the first time)"

Run app.py:

python app.py

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.

Copy the code below into app.py. Replace API_KEY with your API key:

import geckoboard
client = geckoboard.client("API_KEY")

try:
    client.ping()
    print "Authentication successful"

except:
    print "Incorrect API Key"

dataset = client.datasets.find_or_create('sales.by_day', {'amount': { 'type': 'number', 'name': 'Amount', 'optional': False },'timestamp': { 'type': 'datetime', 'name': 'Time' }}, ['timestamp'])
print "Dataset successfully created/located"

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')
print "Data successfully appended"

Run app.py:

python app.py

Next steps

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

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!