Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

Official Python client for the Geckoboard Datasets API

Project Description

A Python client library for Geckoboard datasets API.

Note: This library is still in Beta and the API has potential to change before the release of V1.


Install the package with pip

pip install


The latest documentation and user guide can be found on the Geckoboard developer docs

Getting started

Install the python client from PIP

pip install

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.


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


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)


  • dataset_id [required] <str>
  • fields [required] <dict>
  • unique_by <list>


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.



  • items [required] <list>


  { '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., delete_by)


  • items [required] <list>
  • delete_by <str>

  { '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.



  • dataset_id [required] <str>


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


Clone this repo

git clone && cd geckoboard-python

Install package dependencies

python develop

Run tests

Release History

Release History

This version
History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date (3.8 kB) Copy SHA256 Checksum SHA256 Source Aug 23, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting