# 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+](https://nodejs.org/en/) 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:

```
import { Geckoboard } from 'geckoboard';

const API_KEY = 'YOUR_API_KEY';

const gb = new Geckoboard(API_KEY);

try {
  await gb.ping()
  console.log("success")
} catch (err) {
  console.log(err);
}
```

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.

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

### Datatypes supported by the Datasets API

- **Date format**: All date types must be formatted as `YYYY-MM-DD` (e.g. `2018-01-01`).
- **Datetime format**: Must be formatted as [ISO 8601](https://www.w3.org/TR/NOTE-datetime) strings.
- **Duration format**: Supported units include milliseconds, seconds, minutes, or hours.
- **Money format**: Specify the currency using ISO 4217 currency codes.
- **Number format**: Regular decimal values can be used in number fields.
- **Percentage format**: A number in the `0` to `1` range will be displayed as a percentage.
- **String format**: Must not contain more than 256 characters.

### 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"]
}
```

### 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
    }
  ]
}'
```

### 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": [] }'
```

### Clear all data in a dataset

Wipes clean all the existing data in a dataset by passing an **empty array** via the `PUT` method.

### Limits and quotas

API key limits include **60 requests per minute** and datasets can contain up to **5000 records**.

### Visualization requirements

Your schema determines the visualizations that can be built with your dataset on a Geckoboard dashboard. Ensure to include appropriate types of data for the desired visualizations.