Tutorial

This tutorial explains the most common use case for Ducksboard API, sending data to your dashboard. It should be enough to get you started with using Ducksboard’s custom widgets and allow you to get a feeling of how the API works.

If you want to know more, refer to the full Push API documentation or check out the master Ducksboard API docs to learn about all the APIs offered by Ducksboard.

Overview

To send data to Ducksboard, create a customized widget and make a POST request to push.ducksboard.com with a JSON payload.

An example request is:

curl -v -u APIKEY:x -d '{"value": 10}' https://push.ducksboard.com/values/235

Slots and labels

Every field (called a slot) displayed by a custom widget has a label, which identifies the slot. Labels are typically just numbers, but you can change them to something meaningful for your application, like customers_no or cpu_temp.

Some widgets have just one slot and display only a single value, for instance counter widgets. Some have multiple slots and can show several values at a time, for instance bars widgets.

For information on available slots, see Slot kinds.

Authentication

To authenticate, use HTTP Basic Auth with your API key as the username and anything as the password (the password is ignored, anyway).

Request format

The request payload is a simple JSON object that contains a value or a delta field and an optional timestamp field. If no timestamp is specified, the current time is used.

Deltas can only be used with numeric widgets and should contain the amount to increment (or decrement) the number displayed. Delta timestamps are ignored, they are always treated as differences from the current value.

If both delta and value are specified, value wins.

value required
a number for numeric widgets, an object for widgets requiring a specific format (like timelines)
delta required
an increment (use negative numbers for decrements) for numeric widgets, should be used instead of value
timestamp optional
a UNIX timestamp in seconds (see Wikipedia entry for Unix time)

Note

Keep in mind that timestamps should be expressed in seconds and can have fractional parts. Some programming languages, like Javascript, use milliseconds for timestamps. To get the current timestamp in seconds in Javascript, use new Date().getTime()/1000.

You can either send a single value, or a list of values. Deltas can only be sent on their own and only one at a time.

{ "value": <value> }

{ "delta": <number> }

{ "value": <value>, "timestamp": <number> }

[ { "value": <value> }, ... ]

[ { "value": <value>, "timestamp": <number> }, ... ]

The format for the value depends on the slot you’re pushing data to. For specific information, refer to Slot kinds and Push values format.

Examples

Pushing a single number to a widget with a slot labelled 235

curl -v -u APIKEY:x -d '{"value": 10}' https://push.ducksboard.com/values/235

Incrementing the number in a widget with a slot labelled 235 by one

curl -v -u APIKEY:x -d '{"delta": 1}' https://push.ducksboard.com/values/235

Pushing a list of values with timestamps to a widget with a slot labelled 235

curl -v -u APIKEY:x -d '[{"value": 10, "timestamp": 1332971928.1},
                         {"value": 11, "timestamp": 1332994928.1},
                         {"value": 12, "timestamp": 1333056928.1}]' \
    https://push.ducksboard.com/values/235

Pushing a message to a timeline widget with a slot labelled errors:

curl -v -u APIKEY:x -d '{"value": {
                           "title": "error",
                           "image": "https://app.ducksboard.com/static/img/timeline/red.gif",
                           "content": "something bad happened",
                           "link": "http://example.com/"}}' \
    https://push.ducksboard.com/values/errors

Table Of Contents