NAV Navbar
cURL node.js ruby python
  • Authentication
  • Plan your schema
  • API requests
  • Limits and quotas
  • Visualization requirements
  • Get support

    Datasets API Reference

    Geckoboard's Datasets API is a powerful and flexible way to compile data from in-house systems, third-party tools, and databases on your dashboard.

    To do this you'll need to:

    1. Write a script that connects to your data source and requests the required data.
    2. Create and push a dataset to Geckoboard that includes all the metrics you want to display.

    Authentication

    Find your API key

    Log into your Geckoboard account and follow these steps:

    1. Click your initials in the top right corner and select Account.
    2. On the Account Details screen, scroll down and look for API Key towards the bottom of the page.

    Install a client library

    Create a new directory for your Node.js app. Then, in your terminal, cd to your app’s directory and run:

    npm install geckoboard
    

    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)
    

    You can make calls to the Datasets API with whichever method you usually use to make HTTP requests, but Geckoboard offers client libraries that make interacting with the API even simpler.

    Switch the programming language of the examples with the tabs in the top right. By default, the Datasets API Docs demonstrate using cURL to interact with the API over HTTP.

    If you're on a Unix based OS (Mac, Linux), you likely have cURL installed on your machine (use the curl -V command in your terminal to confirm). Windows users can access the Command Prompt by searching for Command within Cortana.

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

    Make your first API call

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

    You should receive 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 with the #ping method:

    client.ping
    

    Example:

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

    Example:

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

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

    If you missed including the colon : or are still asked for a password, hit Enter in your terminal.

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

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

    Attribute Type Required?
      callback Function Yes

    Plan your schema

    When you’re adding a dataset widget to your dashboard, we’ll look at your schema and present the visualization 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.

    Visualizations are powered by individual datasets, which means you can't combine data from two or more datasets to build a visualization

    Geckoboard can handle data aggregation and grouping, so there’s no need to pre-aggregate your data. And when an update is received via the API, all the widgets powered by that dataset are then updated automatically.

    The Datasets API currently supports the following types:

    Date format

    Example creation:

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

    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 (e.g. 2018-01-01).

    For hours, minutes and seconds, use the Datetime format.

    A date field can be NULL if set as optional.

    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"
        "optional": true
      }
    }
    
    "fields":{
      "datetime":{
        "type": "datetime",
        "name": "Datetime"
        "optional": true
      }
    }
    
    "fields":{
      "datetime":{
        "type": "datetime",
        "name": "Datetime"
        "optional": true
      }
    }
    
    "fields":{
      "datetime":{
        "type": "datetime",
        "name": "Datetime"
        "optional": true
      }
    }
    

    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).

    A datetime field can be NULL if set as optional.

    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.

    Duration format

    "my_duration_field": {
      "name": "My duration field",
      "type": "duration",
      "time_unit": "minutes"
      "optional": true
    }
    
    "my_duration_field": {
      "name": "My duration field",
      "type": "duration",
      "time_unit": "minutes"
      "optional": true
    }
    
    "my_duration_field": {
      "name": "My duration field",
      "type": "duration",
      "time_unit": "minutes"
      "optional": true
    }
    
    "my_duration_field": {
      "name": "My duration field",
      "type": "duration",
      "time_unit": "minutes"
      "optional": true
    }
    

    Example adding data:

    "data":[
      {
        "my_duration_field": 83
      }
    ]
    
    "data":[
      {
        "my_duration_field": 83
      }
    ]
    
    "data":[
      {
        "my_duration_field": 83
      }
    ]
    
    "data":[
      {
        "my_duration_field": 83
      }
    ]
    

    duration fields can be set to milliseconds, seconds, minutes or hours.

    Decimal or integer values can be used. For example, if your field is set to minutes and you send 1.5, that will be displayed as 1m 30s in app.

    A duration field can be NULL if set as optional.

    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. Currency codes should always be in uppercase.

    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 NULL if set as 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 $

    If your currently isn't listed check out the full list of active codes of official ISO 4217 currency names.

    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 NULL if set as optional.

    If you're trying to format a number separated by characters like dots ., dashes -, brackets (), etc, use the String format instead. Examples include telephone numbers ((555) 555-1234) and software versions (5.1234).

    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 NULL if set as optional.

    String format

    Example creation:

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

    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.

    If you're receiving the error post Error: Field "[field_name]" may not contain more than 100 characters despite no entries exceeding the character limit, you may be using double- or triple-byte characters. Some non-latin languages need two or more bytes for representing more complex characters. Consider using a lower character limit or truncating instances of double- or triple-byte characters.

    A string field can be NULL if set as optional.

    API requests

    Find or create a new dataset

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

    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'])
    

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

    Where :id is a string to help you identify your dataset in Geckoboard.

    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.

    Request parameters

    Attribute Type Required? Description
    fields Object Yes An object with keys for each column in your dataset. The value describes the type for that column.
    unique_by Array No An array of one or more field names whose values will be unique across all your records.
    Attribute Type Required Description
    options Object Yes  
        id String Yes  
      fields Object Yes An object with keys for each column in your dataset. The value describes the type for that column.
          type String Yes  
          name String Yes  
          optional Boolean No  
        unique_by Array No An array of one or more field names whose values will be unique across all your records.
    callback Function No  
        error Error | Null Yes  
        dataset Undefined Yes  

    Available field types:

    Attribute Type Required Description
      datasets_id str Yes  
    fields dict Yes An object with keys for each column in your dataset. The value describes the type for that column.
        type str Yes  
        name str Yes  
        optional boolean Yes  
      unique_by Array No An array of one or more field names whose values will be unique across all your records.

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

    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

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

    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 vs replace

    Your particular setup and use case will largely determine which method you use, but 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.

    Consider append when:

    Consider replace when:

    Clear all data in a dataset

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

    Response:

    {}
    
    dataset.put([]);
    
    dataset.put([]) # => true
    
    dataset.put([])
    

    Response:

    True
    

    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.

    This example provides the empty array syntax.

    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

    Specify multiple field names

    Example:

    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.

    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.

    Limits and quotas

    API rate limit

    
      "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.

    If you exceed your limit, the API will return a 429 TOO MANY REQUESTS status and error message.

    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.

    Datasets per account

    Each Geckoboard account is limited to 200 datasets. When the number of datasets is reached, no more datasets can be added. You can delete datasets via the API.

    Update frequency

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

    There's no limitation on the frequency that you can send an update to a dataset, as long as it falls within the rate limit, but the visualizations on your dashboards will only show changes up to every 10 seconds. We'd recommend not updating a dataset more frequently than this.

    Visualization requirements

    Your schema determines 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're building a particular visualization.

    Number visualization

    The number visualization is focused on the display of a metric that can be represented by a single number, along with optional associated secondary metrics, such as a change or trend indication.

    Visualization type Visualization example Required types
    Number Number widget powered by a dataset duration or money or number or percentage
    Number with sparkline comparison Number widget with sparkline comparison powered by a dataset money or number or percentage
    Number with specific time-based sparkline comparison Number widget with sparkline date powered by a dataset money or number or percentage and date or datetime
    Number with percentage comparison Number widget with percentage comparison powered by a dataset money or number or percentage
    Number with number comparison Number widget with number comparison powered by a dataset money or number or percentage
    Number with goal comparison Number widget with goal comparison powered by a dataset money or number or percentage

    Gauge visualization

    Gauges are a great way of representing a single data point that fluctuates over time, like a speedometer in a car. The gauge is most useful to quickly see a metric in comparison to defined minimum and maximum values.

    Visualization type Visualization example Required types
    Gauge Gauge widget powered by a dataset duration or money or number or percentage
    Gauge with needle on specific time-based value Gauge widget powered by a dataset duration or money or number or percentage and date or datetime

    Line Chart

    Line charts are best used to track changes over time, using equal intervals of time between each data point.

    There are two ways to create multi-series line chart using the Datasets API. When creating a multi-series line chart, you’ll need to pick one:

    Visualization type Visualization example Required types
    Line chart multi-series Line chart widget powered by a dataset duration or money or number or percentage
    Line chart X-axis Line chart widget powered by a dataset duration or date or datetime

    Column Chart

    Column chart data is represented by rectangular bars with lengths proportional to the values that they represent. The column chart's discrete data is categorical data and answers the question of "how many?" in each category.

    Visualization type Visualization example Required types
    Column chart metric Column chart widget powered by a dataset duration or money or number or percentage
    Column chart X-axis Column chart widget powered by a dataset duration or date or datetime or string
    Multi-series column chart metric Multi-series column chart widget powered by a dataset duration or money or number or percentage

    Bar Chart

    Bar charts display data using horizontal rectangular bars, where the length of the bar is proportional to the data value. The bar chart's discrete data is categorical data and answers the question of "how many?" in each category.

    Visualization type Visualization example Required types
    Bar chart metric Column chart widget powered by a dataset duration or money or number or percentage
    Bar chart X-axis Column chart widget powered by a dataset duration or date or datetime or string

    Leaderboard visualization

    Leaderboards are a visualization of achievement. Their goal is to make comparisons between people's (or item's) ranks.

    Visualization type Visualization example Required types
    Leaderboard label Leaderboard widget powered by a dataset string
    Leaderboard value Leaderboard widget powered by a dataset money or number or percentage

    Table visualization

    Tables are used to display data from up to 10 columns from a dataset. There are two types of tables:

    Visualization type Visualization example Required types
    Table raw data Table widget powered by a dataset Any data type as long as there are at least two of them
    Table summary Table chart widget powered by a dataset duration or

    money or number or percentage (for columns) and date or datetime or string (for grouping)