Create a new dataset using cURL

Follow this guide to prepare a new Dataset for Geckoboard using cURL.

Before you start

cURL is just one of the programming languages you can use to add a Dataset to Geckoboard. We have also have walkthroughs for Node.js, Ruby, and Python.

We also have a dedicated guide to sending SQL data to datasets using either a MacOS, Linux or Windows machine or server.

Installation

If you're on a Unix based OS (Mac, Linux), you likely have it installed on your machine. Regardless of the OS you're using, you can check with the curl -V command on your terminal to see if you have it installed.

If you need to install cURL, please visit their download page for instructions.

Tip

Windows users can access the Command Prompt by searching for Command within Cortana.Searching for command within Cortana in Windows

Authenticate your account

Test whether your API key is working by pasting the following command to your terminal.

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

Replace your-api-key with your API key. If you missed including the : or are still asked for a password, hit Enter in your terminal.

If authentication is successful {} should be logged to your console.

Note

You can find your API key by following these steps.

Important note

Your Geckoboard API key is just as powerful as your login credentials, so keep it safe. Do not share it in publicly accessible areas such GitHub, client-side code, and so forth.

Get help

If you’re having problems with authentication then you can get in contact with our Customer Success team who can assist you.

Make a dataset

You’ll need to give your dataset an id so that you can find it easily in Geckoboard.

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

Where PUT is the HTTP method that will allow us to create the Dataset and :id is a string to help you identify your dataset from within the application.

Example dataset

In this example we’re creating a dataset with the id sales.by_day.

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

Before you create your first dataset you’ll need to plan your data’s schema. A schema is a collection of fields which will let us know what form your data takes. Learn more about making datasets.

The Datasets API currently supports the following types:

  • date
  • datetime
  • number
  • percentage
  • string
  • money

Important note

You must use lower case letters for field names.

Read more about types.

Add data to the dataset for the first time

To add data to the dataset for the first time, you must use the PUT method (which is normally used to replace all data).

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

Each record you send to the dataset must only include the fields that you specified when you first created the dataset. The value supplied for a field must conform to that field’s type. For example, attempting to store a number in a datetime field will result in an error.

Example of adding data to a dataset for the first time

Here we use the PUT HTTP method with the dataset :id and the data attribute to add or replace data in our Dataset.

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

{}

Append data to the dataset

You can append records to your dataset by using the POST method. These new records will be added to the existing contents of your datasets.

POST https://api.geckoboard.com/datasets/:id/data

Should the number of records in your dataset exceed the limit following a POST the oldest records (by insertion time) will be removed. This behaviour can be overridden by using the delete_by option when appending new records.

Example of appending data to the dataset

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

{}

Next steps

Assuming you’ve encountered no errors, then that’s it! You've created a new dataset using cURL.

You can find more detailed information about configuring your dataset in our API Reference.

You can also find instructions on how to delete this dataset.

Suggested next step

Learn how to create a new widget using your new dataset.

Was this article helpful?

Awesome! 👍  Thanks so much for your feedback!