Guide to using our Datasets API

Before you start

This guide will give you an overview on how to visualize your data from our Datasets API. We've covered how to get your data into Geckoboard as datasets on our Developer Hub.

Our Datasets API is a powerful and flexible way to get data into Geckoboard.

It is particularly useful when you have specific sets of data that you want to display on our dashboards that can’t be accessed by other data sources. It’s also helpful if you want to get data from your own internal systems, or if you need to extend the functionality of a pre-built data source.

Before we go any further, this will be a great time to define a few terms that will help better understand our Datasets integration datasets.

Glossary of terms

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.

Picking a dataset

To get started, simply click on the Add widget button on the top right and search for Datasets API.

Once you access the integration you’ll be taken to screen that lists all the datasets you’ve sent to your Geckoboard account. You’ll also see a default dataset geckoboard.space.cargo that’s available to help you get a better idea of how the integration works before you send your own data.

We'll use this default dataset for all our examples here, so click on geckoboard.space.cargo and we’re good to go.

Setup screen

The first thing you'll notice in the setup screen is that there’s an initial line chart based on the data provided. This is our default visualization and it will work if your data can be used to plot a line chart. You can change it by selecting a different one from our visualization selector. The dataset picker will allow you to change the dataset you’re currently using without having to leave this screen.

In the Widget Setup Area you will set up and define how to visualize the dataset. Any changes to this section will be displayed on the live preview screen to the right.

This area is broken into two sections: Build and Fine-tune. We'll explain the Build section here. Fine-tune is simply a shortcut to the number formatting menu.

Build

This section is unique for each visualization. We’ll cover all options below:

Metric:

In this section of the Setup Area you will find the fields available for each visualization. These fields are populated by the data sent in your dataset. For the Line chart for example, these would be the lines plotted. The type of the fields (Money, Number, Percentage) and their names are defined when you’re setting up the schema.

A powerful option here is the record count. In our example Space Cargo dataset, this means you can now plot the number of orders by day and then split that by category or destination.

To understand why your data is populated in the way it is when you view the field option, it would be helpful at this stage to preview the structure of the original dataset. You can access this preview from the dataset options menu in the navigation bar.

The dataset preview displays the dataset as a spreadsheet and it shows 30 records from the dataset. The names of the fields with their types is visible and helps you understand how exactly your data will be populated on our widget. You can also see the last time the sheet was updated and the number of records included in it.

The preview looks like this:

We can further manipulate the data with two powerful functions:

Aggregate

This is the function used to calculate a roll-up value from related records. The options are Sum (adds all records up and shows the total), Min (displays the minimum value), Max (displays the maximum value), Average (displays the average of all values for that record).

Split

Use this option to break a single line series into multiple series. Splitting consists of grouping together records based on a chosen matching field.

X-Axis:

The X-axis will display the name of the field or a Time value. It accepts the types date and dateTime to display Time or a string to display the name of the field.

What's bucketing?

A time value resulting from the roll-up of a group of records from a given time period. For example “bucket by week”.

Goal:

This option allows you to add a goal to your visualizations. In the example below, the bars that have reached the goal are displayed in green.

Chart options settings:

With these settings you can modify the minimum and maximum of the Y-Axis.

Configure visualizations

From the following visualization types, select you want to configure:

Number

This visualization displays a metric that can be represented by a single number. The number can include a prefix or a suffix to add more context to the number.

There’s the option to add a comparison visualization to the number. In this way the widget will display a primary metric and its relationship with a goal.

Gauge

Gauges are often used to show a data point that changes over time. The gauge would be ideal in cases where a data point needs to be compared with a minimum and maximum value.

It’s possible to add more context by adding a range in which the number is expected to fluctuate. If this is not added manually we will calculate them for you.

Showing progress towards a goal is also possible by enabling the Goal tab and adding a number that’s within the minimum and maximum.

One thing to note is that the gauge will take the last value in the field and use it as its current value.

Line Chart

Line charts are a great way to track changes over time. It’s also possible to plot multiple series of values and visualize the trend of these values over time.

On the setup screen you can choose the metric(s) you want to display. By default there’s only one field populated, however you can add as many fields as your dataset and the size of the widgets allow. Each field will represent a series of values.

It is important to note that in order for us to be able to plot a line chart the dataset must contain datetime fields.

For line charts it is also possible to set comparison styling on one of a line chart’s series. Great for showing period-over-period comparisons, as it keeps the emphasis on the present period while still giving a point of reference.

You’ll find the option in the new Series options menu by clicking the three dots next to any series.

Column Chart

To select a Column chart simply click on the visualization selector and you’re good to go. The chart will respect any settings while you change visualization.

It is important to note that this visualization works best with 10-12 data points, more would make the graph look crammed.

Bar Chart

Very similar to the Column chart, the bar chart is a great visualization to show comparison between several categories. One axis of the chart shows the categories compared, the other axis represents a discrete value.

Note that this visualization would work best if plotting a maximum of 10 -15 data points.

Leaderboard

The leaderboard is the perfect visualization to use when displaying achievement or to show a ranking of people or things.

Our example below will show us the average Cost per destination and rank them based on these values.

Table

The table visualization gives you the power to display columns directly from your dataset on your dashboard either "raw" which is exactly as it in the dataset or "summary" which aggregates data grouped by a (string or date) value in the dataset.

A table is perfect for communicating more detail such as names, values or any other information set up in your dataset.

With this power comes responsibility, however. After all, adding the whole dataset to your dashboard could introduce unnecessary distractions and cause a team to focus on the wrong things. That’s why we’ve made it easy to pick and choose which columns from your dataset are displayed in a table.