NAV Navbar
cURL node.js ruby python
  • API Reference
  • Schemas and types
  • Update frequency
  • Rate Limiting
  • Dataset limits
  • Exporting your data
  • Glossary of terms
  • Datasets API

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

    API Reference

    Quickly review all available resources for Geckoboard's Dataset's API with this reference overview.

    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.

    New to Datasets?

    Learn the basics of the Datasets API, from authentication to building your own dataset, with our Getting Started guides.

    Or, get the most from your experience developing on our Datasets API with our Walkthough articles.

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

    Schemas and types

    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.

    The Datasets API currently supports the following types:

    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.

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

    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.

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