Geckoboard's Datasets API and Custom Widgets are powerful and flexible ways to compile data from in-house systems, third-party tools, and databases on your dashboard.

Postman is a REST client that allows developers to test, develop and document APIs.

Our pre-built Postman collection lets you quickly test our Datasets API and Custom Widgets - no coding required!

Before you start

Install Postman

Download a free version of Postman. The free plan is sufficient for importing and testing this collection.

Import the collection to your Postman workspace

After installing Postman, you can download the collection below and import it into your own environment.

Demo video - Importing the collection to Postman

Find your Geckoboard API key

You will need your API key to hand for each of these methods so it is best to have this ready now. You can find your Geckoboard API key using these steps.

Modify the collection (optional)

If you're only testing our methods, don't change the dataset id or the content contained in the Body.

If you would like to use your own schema, our developer documentation provides a complete reference to the schema, field definitions, and API requests, along with examples. Please refer to the documentation to plan your dataset schema and modify the requests in our Postman collection as per your needs.

If you get stuck at any point or run into issues, please get in touch, and we'll be happy to help!

Learn about the Datasets API methods

The methods we are going to cover are each of the methods detailed within our Developer Documentation, these are the GET, PUT, POST and DELETE methods.

GET - This method is used to test the connection between your endpoint and the Geckoboard API, using your API key identifies your individual account as the endpoint.
PUT - This method can be used to create a Dataset or replace the contents of an existing Dataset. It is at this point you will need to know the structure of your Dataset (if you are planning on creating your own schema). You can see more about planning your schema and supported data types in our developer documentation.
- NOTE: This is a destructive method and when used with an existing Dataset, will completely overwrite the existing data replacing it with the specified payload. You should only do this if you are absolutely certain that you will not need the overwritten data as this cannot be undone.
POST -This method can be used to add data to a Dataset, This method is non destructive and POSTS data to your specified Dataset by adding it on the end of the existing data entries.
DELETE - This method is used when you would like to completely delete the Dataset and all of its data.

Use Postman to test the Datasets API methods

Test the Datasets authentication using the GET method

Select the GET: Datasets authentication method.
Make sure the URL is set to https://api.geckoboard.com/
Under the Authorisation tab, select the Type as Basic Auth.
Fill in your Geckoboard API key in the Username field.
Leave the Password field empty.
Make the request by clicking on Send.

Tip: A {} response indicates a 200 OK Status has been received. In other words, the {} response confirms the authentication was successful.

Demo video: Testing the authentication using the Postman collection

Create a dataset using the PUT method

Select the PUT: Create dataset method.
Update the dataset name, if needed, in the URL like so: https://api.geckoboard.com/datasets/<your-dataset-name>. We've set the dataset name to postman_example in our example.
Under the Authorisation tab, select the Type as Basic Auth.
Fill in your Geckoboard API key in the Username field.
Leave the Password field empty.
In the Headers tab, add Content-Type in the KEY field and application/json in the VALUE field. Please refer to our demo video below if you need help with any of these steps.
Under the Body tab, select raw and add your dataset schema here. Our collection includes a sample schema that you can use directly without modifications.
Make the request by clicking on Send.

Tip: Use the Save Response option to download the dataset schema response. You can use this as a reference, if needed, for pushing data to the dataset later on.

Demo video: Creating a Dataset using the Postman collection

Add or append data to your Dataset using the POST method

Select the POST: Add or append data method.
Make sure you have the correct dataset name in the URL in the following format: https://api.geckoboard.com/datasets/postman_example/data. As before, we've set the dataset name to _postman_example in our example.
Under the Authorisation tab, select the Type as Basic Auth.
Fill in your Geckoboard API key in the Username field.
Leave the Password field empty.
In the Headers tab, add Content-Type in the KEY field and application/json in the VALUE field. Please refer to our demo video below if you need help with any of these steps.
Under the Body tab, select raw and add your dataset payload here. Our collection includes a sample payload that you can use directly without modifications.
Make the request by clicking on Send.

Tip: A {} response indicates a 200 OK Status has been received. In other words, the {} response confirms the data has been posted successfully.

Demo video: Adding data to a Dataset using the Postman collection

Replace all of the data in your Dataset using the PUT method

Select the PUT: Replace data method.
Make sure you have the correct dataset name in the URL in the following format: https://api.geckoboard.com/datasets/postman_example/data. As before, we've set the dataset name to _postman_example in our example.
Under the Authorisation tab, select the Type as Basic Auth.
Fill in your Geckoboard API key in the Username field.
Leave the Password field empty.
In the Headers tab, add Content-Type in the KEY field and application/json in the VALUE field. Please refer to our demo video below if you need help with any of these steps.
Under the Body tab, select raw and add your dataset payload here. Our collection includes a sample payload that you can use directly without modifications.
Make the request by clicking on Send.

Tip: A {} response indicates a 200 OK Status has been received. In other words, the {} response confirms the data has been pushed successfully.

Demo video: Replacing the data in a Dataset using the Postman collection

Delete all of the data and the Dataset using the DELETE method

Select the DEL Delete a dataset method.
Make sure you have the correct dataset name in the URL in the following format: https://api.geckoboard.com/datasets/<your-dataset-name> As before, we've set the dataset name to _postman_example .
Under the Authorisation tab, select the Type as Basic Auth.
Fill in your Geckoboard API key in the Username field.
Leave the Password field empty.
Make the request by clicking on Send.

Tip: A {} response indicates a 200 OK Status has been received. In other words, the {} response confirms the dataset has been deleted successfully.

Demo video: Deleting the data in a Dataset using the Postman collection

Use Postman to test Custom Widgets

Create a new request or use one of the examples
Select POST
Update the URL to reflect the following and be sure the widget key is added: https://push.geckoboard.com/v1/send/widget-key-here
Select the Headers tab
In the Key field and add Content-Type
In the Value field add application/json or application/xml
On the Body tab, select Raw
Add your data formatted as JSON or XML as per our documentation
Click Send to POST payload to Geckoboard