API Operations

Find or create a new dataset

PUT is the HTTP method for retrieving resources from the Datasets API.

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

Where :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"]
}
unique_by
An optional array of one or more field names whose values will be unique across all your records.
fields
an object with keys for each column in your dataset. The value describes the type for that column.

We'll use the findOrCreate method.

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"]
}
unique_by
An optional array of one or more field names whose values will be unique across all your records.
fields
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

We'll use the find_or_create method.

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])
unique_by
An optional array of one or more field names whose values will be unique across all your records.
fields
an object with keys for each column in your dataset. The value describes the type for that column.

Available field types:

  • DateField
  • DateTimeField
  • NumberField
  • PercentageField
  • StringField
  • MoneyField

We'll use the find_or_create method.

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'])
unique_by
An optional array of one or more field names whose values will be unique across all your records.
fields
an object with keys for each column in your dataset. The value describes the type for that column.
Attribute Type Required?
  datasets_id str Yes
fields dict Yes
    type str Yes
    name str Yes
    optional boolean Yes
  unique_by Array No

Append data to your dataset

Append will add new records to OR modify the already existing records within your dataset. It calls 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 or if you want to fix an incorrect record.

Should the number of records in your dataset exceed the 5000 records limit following an Append, old records will be discarded.

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-02-01T12:00:00Z",
      "amount": 819
    },
    {
      "timestamp": "2018-02-02T12:00:00Z",
      "amount": 409
    },
    {
      "timestamp": "2018-02-03T12:00:00Z",
      "amount": 164
    }
  ]
}'

Response:

{}
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.
dataset.post(items, options, callback);

Example

[
  { timestamp: "2018-02-01T12:00:00Z", amount: 8192 },
  { timestamp: "2018-02-02T12:00:00Z", amount: 4096 },
  { timestamp: "2018-02-03T12:00:00Z", amount: 16384 }
];
{
  delete_by: "timestamp";
}
Attribute Type Required?
  items Array Yes
options Object | Null No
    delete_by String No
callback Function No
    error Error | Null No
dataset.post(items, delete_by: optional_name_of_a_date_or_datetime_field)

Example

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

Example

dataset.post([
  { 'timestamp': '2018-02-03T12:00:00Z', 'amount': 312 },
  { 'timestamp': '2018-02-04T12:00:00Z', 'amount': 665 },
  { 'timestamp': '2018-02-05T12:00:00Z', 'amount': 453 }
], 'timestamp')
Attribute Type Required?
  items list Yes
  delete_by str No

Replace all data in a dataset

Replace will delete all the existing data within the dataset and then write the new data.

In effect, your dataset will contain only the new records that you just pushed (you can think of it as similar to an overwrite action).

It calls the PUT method.

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:

{}
data
An array of objects with key + values representing a record in your dataset.
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 }
],
{}
Attribute Type Required?
  items Array Yes
callback Function No
    error Error | Null No
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 }
])
Attribute Type Required?
  items list Yes

When to use replace versus append

Using append, in combination with unique_by and delete_by) is nearly always preferable as it's quicker, provides better performance, and lets you send more data to Geckoboard.

While there may be other considerations to take into account for your particular setup and use case, which method to use comes down to:

  1. How you're extracting the data
  2. How frequently you want to push data
  3. How many records pushed by request

How you're extracting the data

If you’re always getting data for right now from your data source and want to build up a historical record in your dataset, you need to use append. This will let you plot trends over time and also let you display comparisons such as today vs yesterday, this month vs previous month, and so on.

Examples

  1. The Twitter API lets you fetch only the current number of followers. So, you can fetch followers each day and Append it to your Dataset. This will let you plot a line chart of your number of followers over time.
  2. You can also create a Number widget displaying your followers say today vs yesterday, this month vs previous month, etc. (Note: While creating the Datasets Number widget on your dashboard, you’ll need to use the Aggregate = Latest option for achieving such a comparison visualization).

If you’re not interested in maintaining historical data or displaying a comparison, OR you’re able to pull the complete data for the entire time period you’re interested in, you can consider using Replace.

Examples

  1. You want to display the names of the customer support agents currently online on your phone help desk system.
  2. You want to display your total sales this month which is available via a single API query to your billing system.

How frequently you want to push data

Replace first deletes all the existing records within the dataset and then writes the new data. This is a slower and costlier operation to perform as compared to Append.

If you’re planning to push data more than once every few minutes, we would recommend using Append as it’ll be faster and give you better performance. Even if say you’re updating a dataset that contains only a single record (i.e. something you might consider using Replace for), if you’re planning to push frequently, we would recommend using Append in combination with unique_by instead.

Example

You’re tracking the price of Bitcoin on your dashboard and want to update the price every 10 seconds. We would recommend using Append in combination with unique_by.

Number of records pushed by request

A single Replace or Append request will accept a maximum of 500 records. If you want to push more than 500 records to your dataset, you’ll need to send multiple requests using Append.

In conclusion: append is preferable

Clear all data within a dataset

Wipes clean all the existing data in a dataset by passing an empty array via the PUT method (i.e. Replace) and leaves behind an empty dataset. The dataset itself and its schema will be preserved though.

Example

The example provides the empty array syntax when using Curl.

curl https://api.geckoboard.com/datasets/sales.by_day/data \
  -X PUT \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{ "data": [] }'

Response:

{}

The example provides the empty array syntax when using Node.js.

dataset.put([]);
dataset.put([])

Example

The example provides the empty array syntax when using Ruby.

dataset.put([]) # => true
dataset.post(items, delete_by)

Example

The example provides the empty array syntax when using Python.

dataset.put([])

Response:

True

Delete a dataset

Deletes the dataset and all data with the given id.

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

Example

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

Response:

{}

Deletes the dataset and all data therein.

dataset.delete(callback);
Attribute Type Required?
callback Function No
    error Error | Null No

Deletes the dataset and all data with the given id.

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

Deletes the dataset and all data with the given id.

client.datasets.delete(dataset_id)

Example

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

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

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

Specify multiple field names

You can specify multiple field names as part of unique_by as long as they are string, date or datetime fields and have unique identifiers.

Example

Here’s an example using Node.

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'
      },
      name: {
        type: 'string',
        name: 'Name'
      }
    },
    "unique_by": ["date", "name"]
  },
  function (err, dataset) {
    if (err) {
      console.error(err);
      return;
    }

    dataset.put(
      [
        { date: '2016-01-01', quantity: 819, gross: 2457000, name: "one" },
        { date: '2016-01-02', quantity: 409, gross: 1227000, name: "two" },
        { date: '2016-01-02', quantity: 415, gross: 1229523, name: "two" },
        { date: '2016-01-03', quantity: 164, gross: 492000, name: "three" }
      ],
      function (err) {
        if (err) {
          console.error(err);
          return;
        }

        console.log('Dataset created and data added');
      }
    );
  }
);

The dataset, when checked, contains only 3 rows, despite sending 4. This is because one counts as a duplicate under those conditions. Only the later one is kept.

Passing null values

All fields can be NULL if set to optional. In other words, when set to optional=true when the field is created.

Glossary

Dataset
A name, fields and corresponding data that make up one completed data API integration.
Schema
The defined structure of a dataset (a group of fields).
Field
A column in spreadsheet terms. Structural, rather than referring to actual data. Has, at minimum, a name and a type.
Name
The developer-friendly designation that is used as a unique identifier for both either a data set or field. URL-friendly.
Type
Required when defining a field. Tells Geckoboard and the user what sort of data is expected in a field.
Record
A row in spreadsheet terms. A single collection of data that fit into the data set’s structure.
Bucketing
To ‘roll-up’ a group of records from a given time period into one value. For example “bucket by week”.
Aggregate
The function used to calculate the ‘rolled-up’ value when bucketing. For example, sum, average, min, max.
Split
To break a series into multiple series by grouping together records based on a chosen matching field.
Count
An alternative aggregate, the number of records in a given time period.
Was this article helpful?

Awesome! 👍 Thanks so much for your feedback!

Sorry about that! Start a conversation now.

We're ready to help, 24 hours a day, 5 days a week

Get support
  • Fernanda Customer Success Avatar

    Megan

    USA
  • Hariharan Customer Success Avatar

    Hariharan

    India
  • Fernanda Customer Success Avatar

    Yasmin

    Spain
  • Luis Customer Success Avatar

    Luis

    UK
  • Richard Customer Success Avatar

    Richard

    UK
  • Fernanda Customer Success Avatar

    Fernanda

    Brazil
  • Heather Customer Success Avatar

    Heather

    USA