API Properties

This article details the types of data you'll need in your dataset schema to build each visualization type.

Date format

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

Date examples

Creation

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

Adding data:

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

Datetime format

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, 2020, 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

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

01 through 31

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.

Datetime examples

Creation

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

Adding data:

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

Duration format

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.

Duration examples

Creation

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

Adding data:

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

Money format

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

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

$

Don't see your currency here? Check out the full list of active codes of official ISO 4217 currency names.

Money examples

Creation

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

Adding data:

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

Number format

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

Number examples

Creation

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

Adding data:

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

Percentage format

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.

Percentage examples

Creation

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

Adding data:

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

String format

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.

Strong examples

Creation

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

Adding data:

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

Required types for each visualization

Make sure to include these types of data in your schema if you're building a particular visualization.

number widget icon
gauge widget icon
line chart widget icon
column chart widget icon
bar chart widget icon
leaderboard widget icon
table widget icon

 

Note

To add “today” as a filter for your visualization, you’ll need to use datetime, rather than date) as data type.

Numeric types such as number, money and percentage can be NULL if set to "optional". In other words, when set to optional=true when the numeric field is created).

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

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

money or number or percentage

Gauge with needle on specific time-based value

Gauge widget powered by a dataset

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:

  • Having Line Chart Series with identical data types (i.e. all of them money)
  • Having a string value in the dataset to “split by” (which automatically generates series for each different string value)
Visualization type
Visualization example
Required types

Line chart multi-series

Line chart widget powered by a dataset

money or number or percentage

Line chart X-axis

Line chart widget powered by a dataset

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

money or number or percentage

Column chart X-axis

Column chart widget powered by a dataset

date or datetime or string

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

money or number or percentage

Bar chart X-axis

Column chart widget powered by a dataset

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:

  • Raw data: A row for each record showing the raw data.
  • Summary: Aggregated data, grouped by a string or date.
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

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

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