NAV Navbar
cURL node.js ruby python
  • Welcome
  • Before you start
  • API Calls
  • Schemas and types
  • Update frequency
  • Rate Limiting
  • Dataset limits
  • Exporting your data
  • Glossary of terms
  • Walkthroughs
  • Send SQL data to datasets
  • Datasets API

    A simple, powerful way to access your most important data with Geckoboard.

    Welcome

    Welcome to Geckoboard's Datasets API – a simple yet highly flexible way of building live TV dashboards from data in third-party tools, databases and in-house systems.

    You can view code examples in the area to the right, and you can switch the programming language of the examples with the tabs in the top right. We provide examples in cURL, Node.js, Ruby, and Python, but you can use any programming language of your choice.

    Whether you have a question about the API, are looking for tips for configuring widgets or advice on which metrics to track, our Customer Success team is here and happy to help!

    Before you start

    What is a dataset?

    Datasets are best thought of as tables. Here’s an example:

    Product
    string
    Unit cost
    money (USD)
    Sales
    number
    Profit margin
    percentage
    Shipping date
    date
    Papayas $9 800K 55% 2018-03-07
    Mangos $6.60 300K 48% 2018-03-14
    Pineapples $5.60 250K 44% 2016-03-21

    Your dataset’s schema defines the columns of this table to let Geckoboard know what form your data takes. You can include up to 10 different fields in a dataset, so one dataset can easily power a whole dashboard.

    A well thought-through schema will make it much easier to configure your widgets when it comes to adding them to your Geckoboard dashboard.

    It’s important to note the relationship between the way you are able to visualize the dataset and the schema it uses.

    When you’re adding a dataset widget to your dashboard, we’ll look at your schema and present the options that make sense for the types of data you’re sending us.

    For example, to plot a line chart the dataset must contain the date or datetime types.

    We recommend you read the schema formatting and visualization types section to see which ones are available and how to shape your schema for a particular one.

    If you still have questions, please get in touch.

    Why use a dataset?

    A dataset is particularly useful when you have specific sets of data that you want to display on a dashboard that can’t be accessed by the integrations Geckoboard currently support.

    It’s also helpful if you want to get data from your own internal systems, or if you need to extend the functionality of one of our pre-built integrations.

    Where to get help?

    The Datasets API is designed for developers, engineers, or anyone else who’s comfortable creating custom-coded solutions or integrating with APIs.

    If you think you may need some help integrating with Datasets, visit our Developer Community or reach out to our helpful Customer Success team.

    Though we don't provide in-house development services, please ask about our partnership with Saasler, who can build datasets out of your data. For more information and pricing, download the PDF (3.8MB).

    API Calls

    Require node library:

    const gb = require("geckoboard")(apiKey);
    

    To begin, add this line to your application’s Gemfile:

    gem 'geckoboard-ruby'
    

    And then execute:

    $ bundle
    

    Or install it yourself as:

    $ gem install geckoboard-ruby
    

    Require the gem and create an instance of the client:

    require 'geckoboard'
    client = Geckoboard.client(api_key)
    

    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 = geckoboard.client(API_KEY)
    

    An API call is a specifically formatted HTTP request to a web server, which will answer the request with an HTTP response.

    The Datasets API only accepts secure connections, so you must make all requests over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

    Authentication

    Test if your API key is working with the following command. Replace your-api-key with your API key:

    curl https://api.geckoboard.com/ -u "your-api-key:"
    

    You should get a 200 response containing {}

    Ping to authenticate:

    gb.ping(callback);
    

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

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

    client.ping
    

    Example:

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

    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
    

    Authenticate your account when using the API by including your personal API key, followed by a colon :, in the request.

    If you missed including the : or are still asked for a password, simply hit the Enter key on your terminal.

    Authenticate your account when using the API by including your personal API key in the request.

    Authenticate your account when using the API by including your personal API key in the request.

    Authenticate your account when using the API by including your personal API key in the request.

    Attribute Type Required?
      callback Function Yes

    Find or create a new dataset

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

    Here's an example:

    curl https://api.geckoboard.com/datasets/sales.by_day \
      -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.by_day",
      "fields": {
        "amount": { "type": "number", "name": "Amount", "optional": false },
        "timestamp": { "type": "datetime", "name": "Date" }
      },
      "unique_by": ["timestamp"]
    }
    
    gb.datasets.findOrCreate(options, callback)
    

    Example:

    {
      "id": "sales.by_day",
      "fields": {
        "amount": { "type": "number", "name": "Amount", "optional": false },
        "timestamp": { "type": "datetime", "name": "Time" }
      },
      "unique_by": ["timestamp"]
    }
    
    client.datasets.find_or_create(id, fields: fields)
    

    Example:

    dataset = client.datasets.find_or_create('sales.by_day', fields: [
      Geckoboard::MoneyField.new(:amount, name: 'Amount', currency_code: 'USD', optional: false),
      Geckoboard::DateTimeField.new(:timestamp, name: 'Time'),
    ], unique_by: [:timestamp])
    
    client.datasets.find_or_create(dataset_id, fields, unique_by)
    

    Example:

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

    Find and verify an existing dataset or create a new one.

    Find and verify an existing dataset or create a new dataset with the findOrCreate method.

    Find and verify an existing dataset or create a new dataset with the find_or_create method.

    Find and verify an existing dataset or create a new dataset with the find_or_create method.

    id is a string to help you identify your dataset from within the application. It may only contain lowercase alphanumeric characters, dots, hyphens, and underscores.

    unique_by is an optional array of one or more field names whose values will be unique across all your records.

    fields is an object with keys for each column in your dataset. The value describes the type for that column.

    Attribute Type Required?
    options Object Yes
        id String Yes
      fields Object Yes
          type String Yes
          name String Yes
          optional Boolean No
        unique_by Array No
    callback Function No
        error Error | Null Yes
        dataset Undefined Yes

    Available field types:

    Attribute Type Required?
      datasets_id str Yes
    fields dict Yes
        type str Yes
        name str Yes
        optional boolean Yes
      unique_by str No

    Replace all data in a dataset

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

    Example:

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

    Response:

    {}
    
    dataset.put(items, callback);
    

    Example:

    [
      { timestamp: "2018-01-01T12:00:00Z", amount: 8192 },
      { timestamp: "2018-01-02T12:00:00Z", amount: 4096 },
      { timestamp: "2018-01-03T12:00:00Z", amount: 16384 }
    ];
    
    dataset.put(items)
    

    Example:

    dataset.put([
      {
        timestamp: DateTime.new(2018, 1, 2, 12, 0, 0),
        amount: 40900
      },
      {
        timestamp: DateTime.new(2018, 1, 3, 12, 0, 0),
        amount: 16400
      }
    ])
    
    dataset.put(items)
    

    Example:

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

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

    Attribute Description
      data An array of objects with key + values representing a record in your dataset.
    Attribute Type Required?
      items Array Yes
    callback Function No
        error Error | Null No
    Attribute Type Required?
      items list Yes

    Append data to a dataset

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

    Example:

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

    Response:

    {}
    
    dataset.post(items, options, callback);
    

    Example:

    [
      { timestamp: "2018-01-01T12:00:00Z", amount: 8192 },
      { timestamp: "2018-01-02T12:00:00Z", amount: 4096 },
      { timestamp: "2018-01-03T12:00:00Z", amount: 16384 }
    ];
    
    {
      delete_by: "timestamp";
    }
    
    dataset.post(items, delete_by: optional_name_of_a_date_or_datetime_field)
    

    Example:

    dataset.post([
      {
        timestamp: DateTime.new(2018, 1, 2, 12, 0, 0),
        amount: 40900
      },
      {
        timestamp: DateTime.new(2018, 1, 3, 12, 0, 0),
        amount: 16400
      }
    ], delete_by: :timestamp)
    
    dataset.post(items, delete_by)
    

    Example:

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

    Append records to a dataset by calling the post method.

    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.

    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.
    Attribute Type Required?
      items Array Yes
    options Object | Null No
        delete_by String No
    callback Function No
        error Error | Null No
    Attribute Type Required?
      items list Yes
      delete_by str No

    Delete a dataset

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

    Example:

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

    Response:

    {}
    
    dataset.delete(callback);
    
    client.datasets.delete(id)
    

    Example:

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

    You can also delete a dataset by calling the #delete method on an instance of Geckoboard::Dataset.

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

    Example:

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

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

    Deletes the dataset and all data with the given id.

    Deletes the dataset and all data therein.

    Deletes the dataset and all data with the given id.

    Deletes the dataset and all data with the given id.

    dataset = client.datasets.find_or_create(...)
    dataset.delete() # => true
    
    Attribute Type Required?
    callback Function No
        error Error | Null No

    Schemas and types

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

    The Datasets API currently supports the following types:

    Schema formatting and visualization types

    Your schema will determine the visualizations that can be built with your dataset on a Geckoboard dashboard.

    Make sure to include these types of data in your schema if you are after a particular visualization.

    Number

    Number: money OR number OR percentage
    Number with sparkline comparison: money OR number OR percentage
    Number with specific time-based sparkline comparison: money OR number OR percentage AND date OR datetime
    Number with percentage comparison: money OR number OR percentage
    Number with number comparison: money OR number OR percentage
    Number with goal comparison: money OR number OR percentage

    Geck-O-Meter

    Geck-O-Meter: money OR number OR percentage
    Geck-O-Meter with needle on specific time-based value: money OR number OR percentage AND date OR datetime

    Line Chart

    Line Chart Series: money OR number OR percentage
    Line Chart X-Axis: date OR datetime

    Column Chart

    Column Chart Metric: money OR number OR percentage
    Column Chart X-Axis: date OR datetime OR string

    Bar Chart

    Bar Chart Metric: money OR number OR percentage
    Bar Chart X-Axis: date OR datetime OR string

    Leaderboard

    Leaderboard Label: string
    Leaderboard Value: money OR number OR percentage

    Table

    Raw Table: Any data type as long as there are at least two of them.
    Summary Table: money OR number OR percentage (for columns) AND date OR datetime OR string (for grouping)

    Date format

    Example creation:

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

    Example adding data:

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

    All date types must be formatted as YYYY-MM-DD (eg 2018-01-01).

    Element Description Notes
    YYYY Four-digit year
    MM Two-digit month Use leading 0 for 1-9
    DD Two-digit day of month 01 through 31

    Datetime format

    Example creation:

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

    Example adding data:

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

    datetime fields must be formatted as ISO 8601 strings, the International Standard for the representation of dates and times.

    We recommend you use the YYYY-MM-DDThh:mm:ssTZD variation, which will produce values that look like 2018-01-01T12:00:30Z (1st January, 2018, 12:00:30 pm, UTC).

    Element Description Notes
    YYYY Four-digit year
    MM Two-digit month Use leading 0 for 1-9
    DD Two-digit day of month 01 through 31
    hh Two digits of hour 00 through 23. 24-hour clock only.
    mm Two digits of minute 00 through 59
    ss Two digits of second 00 through 59
    TZD Time zone designator Use Z for UTC or +hh:mm or -hh:mm. A time zone offset of +hh:mm or -hh:mm indicates that the date/time uses a local time zone which is hh hours and mm minutes ahead of or behind UTC.

    Money format

    Example creation:

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

    Example adding data:

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

    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.

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

    A money field can be optional.

    Currency ISO 4217 code Symbol
    Australian dollar AUD A$
    British pound sterling GBP £
    Canadian dollar CAD C$
    Chinese renminbi CNY
    Euro EUR
    Japanese yen JPY ¥
    Mexican peso MXN $
    Swedish krona SEK kr
    Swiss franc CHF Fr
    United States dollar USD $

    Number format

    Example creation:

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

    Example adding data:

    "data":[
      {
        "number": 42
      }
    ]
    
    "data":[
      {
        "number": 42
      }
    ]
    
    "data":[
      {
        "number": 42
      }
    ]
    
    "data":[
      {
        "number": 42
      }
    ]
    

    number fields can be optional.

    Percentage format

    Example creation:

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

    Example adding data:

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

    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.

    String format

    Example creation:

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

    Example adding data:

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

    All string fields must not contain more than 100 characters.

    Update frequency

    Widgets powered by datasets update in real-time when new data is received.

    Rate Limiting

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

    There is basic rate limiting on the API. This restricts you to 60 requests per minute for your API key.

    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.

    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.

    Exporting your data

    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.

    Glossary of terms

    API key
    An authorization code used to identify you as the requester.
    Authentication
    Used to identify you as the user of the API.
    Field
    A 'column' in spreadsheet terms. Structural, rather than referring to actual data. Has (at minimum) a name and a type.
    Get
    The HTTP method for retrieving resources from the Datasets API.
    Name
    The developer-friendly designation that is used as a unique identifier for both either a data set or field. URL-friendly.
    Post
    The HTTP method for creating resources with the Datasets API.
    Put
    The HTTP method for updating resources with the Datasets API.
    Rate limiting
    Limits the consumption of the Datasets API to a certain number of requests per period of time (set as 60 requests per minute for your API key).
    Record
    A 'row' in spreadsheet terms. A single collection of data that fit into the data set’s structure.
    Schema
    The defined structure of a dataset (a group of fields).
    Type
    Required when defining a field. Tells Geckoboard and the user what sort of data is expected in a field.

    Walkthroughs

    How to create a dataset

    For instructions and code blocks, set your language to cURL or Node.js. 👆

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

    Follow this guide to add your first Dataset to Geckoboard using Node.js.

    For instructions and code blocks, set your language to cURL or Node.js. 👆

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

    Step 1: Installation

    First, create a new directory for your Node.js app.

    Now in your terminal, cd to your app’s directory and run:

    npm install geckoboard
    

    Install the python client from PIP

    pip install geckoboard.py
    

    If you're on a Unix based OS (Mac, Linux), you likely have it installed on your machine. Regardless of the OS you're using, You can check with the curl -V command on your terminal to see if you have it installed.

    We’ll be using the Geckoboard Node.js library to make a simple Node.js app. Node.js version 4+ is required.

    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.

    Step 2: Authenticate your account

    Test whether your API key is working by pasting this command to your terminal. Replace your-api-key with your API key. If you missed including the : or are still asked for a password, simply hit the Enter key on your terminal.

    curl https://api.geckoboard.com/ -u "your-api-key:"
    

    Create a file called app.js and add the code below. Replace your-api-key with your API key:

    var API_KEY = "your-api-key";
    
    var gb = require("geckoboard")(API_KEY);
    
    gb.ping(function(err) {
      if (err) {
        console.error(err);
        return;
      }
    
      console.log("Authentication successful");
    });
    

    Run app.js in your terminal:

    
    node app.js
    

    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
    

    Step 3: Make a dataset

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

    Where PUT is the HTTP method that will allow us to create the Dataset and :id is a string to help you identify your dataset from within the application.

    Example:

    curl https://api.geckoboard.com/datasets/sales.by_day \
      -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.by_day",
      "fields": {
        "amount": { "type": "number", "name": "Amount", "optional": false },
        "timestamp": { "type": "datetime", "name": "Date" }
      },
      "unique_by": ["timestamp"]
    }
    

    Copy the code below into app.js. Replace your-api-key with your API key:

    Should anything fail then err should give you some specifics around what went wrong.

    var API_KEY = "your-api-key";
    
    var gb = require("geckoboard")(API_KEY);
    
    gb.datasets.findOrCreate(
      {
        id: "sales.by_day",
        fields: {
          quantity: {
            type: "number",
            name: "Number of sales"
          },
          gross: {
            type: "money",
            name: "Gross value of sales",
            currency_code: "USD"
          },
          date: {
            type: "date",
            name: "Date"
          }
        }
      },
      function(err, dataset) {
        if (err) {
          console.error(err);
          return;
        }
    
        console.log("Dataset created");
      }
    );
    

    Run app.js in your terminal:

    
    node app.js
    

    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
    

    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. Learn more about making datasets.

    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.

    The Datasets API currently supports the following types:

    Read more about types.

    Step 4: Add data to the dataset for the first time

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

    Here we use the PUT HTTP method with the dataset :id and the data attribute to add or replace data in our Dataset.

    Example:

    curl https://api.geckoboard.com/datasets/sales.by_day/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:

    {}
    

    Add the data with dataset.put as per the example below. Replace your-api-key with your API key:

    var API_KEY = "your-api-key";
    
    var gb = require("geckoboard")(API_KEY);
    
    gb.datasets.findOrCreate(
      {
        id: "sales.by_day",
        fields: {
          quantity: {
            type: "number",
            name: "Number of sales"
          },
          gross: {
            type: "money",
            name: "Gross value of sales",
            currency_code: "USD"
          },
          date: {
            type: "date",
            name: "Date"
          }
        }
      },
      function(err, dataset) {
        if (err) {
          console.error(err);
          return;
        }
    
        dataset.put(
          [
            { date: "2016-01-01", quantity: 819, gross: 2457000 },
            { date: "2016-01-02", quantity: 409, gross: 1227000 },
            { date: "2016-01-03", quantity: 164, gross: 492000 }
          ],
          function(err) {
            if (err) {
              console.error(err);
              return;
            }
    
            console.log("Dataset created and data added");
          }
        );
      }
    );
    

    Run app.js in your terminal:

    
    node app.js
    

    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
    

    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.

    Step 5: Append data to the dataset

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

    Example:

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

    Response:

    {}
    
    var API_KEY = "your-api-key";
    
    var gb = require("geckoboard")(API_KEY);
    
    gb.datasets.findOrCreate(
      {
        id: "sales.by_day",
        fields: {
          quantity: {
            type: "number",
            name: "Number of sales"
          },
          gross: {
            type: "money",
            name: "Gross value of sales",
            currency_code: "USD"
          },
          date: {
            type: "date",
            name: "Date"
          }
        }
      },
      function(err, dataset) {
        if (err) {
          console.error(err);
          return;
        }
    
        dataset.post(
          [{ date: "2016-01-04", quantity: 42, gross: 52000 }],
          {},
          function(err) {
            if (err) {
              console.error(err);
              return;
            }
    
            console.log("Data added");
          }
        );
      }
    );
    

    Run app.js in your terminal:

    
    node app.js
    

    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
    

    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.

    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.

    Step 6: Create a widget

    Assuming you’ve encountered no error, then that’s it. Congratulations, you’ve created your first dataset!

    Now that you’ve created a dataset, go ahead and create a widget. Head to Geckoboard, click Add Widget, choose Datasets as your data source and select your dataset from the list.

    Of course you can also delete this dataset.

    You can find more detailed information in the API Reference section.

    Send SQL data to datasets

    SQL-Dataset is a command line app that quickly and easily integrates your Microsoft SQL Server, MySQL, Postgres and SQLite databases with Geckoboard. Rather than having to work with client libraries and write code to connect to and query your database, with SQL-Dataset all you need to do is fill out a simple config file and run the program from the command line.