HTTP Pull API¶
Overview¶
The HTTP part of the Pull API uses HTTPS and only accepts GET requests. All HTTP resources return JSON. Access is through pull.ducksboard.com.
An example request is:
curl -v -u APIKEY:x https://pull.ducksboard.com/values/235/since?seconds=3600
Client errors¶
The API will respond with HTTP error codes 404 Not Found or 400 Bad Request when an authenticated request cannot be fulfilled. See the section on authentication for more possible responses. Error resposes are JSON-formatted and include an errors field with simple diagnostic information:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{"errors": "unrecognized timezone"}
You might get other error codes as well, like 500 Internal Server Error. This means we did something wrong, please report it to support@ducksboard.com.
Authentication¶
All requests are authenticated using HTTP Basic Authentication, with your API key being the username. The password is ignored:
curl -v -u APIKEY:x https://pull.ducksboard.com/values/805/last
Accessing a resource with an invalid API key will generate a 401 Unauthorized HTTP response. Using the API key of a user that does not have permissions to access a particular resource will generate a 403 Forbidden HTTP response. For instance, if using an invalid key:
curl -v -u invalidapikey:x https://pull.ducksboard.com/values/801/last
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Ducksboard pull API"
But if using a correct key, but trying to access data source 1000, which does not belong to the authenticated user:
curl -v -u correctkey:x https://pull.ducksboard.com/values/1000/last
HTTP/1.1 403 Forbidden
Resource endpoints¶
values¶
The values endpoint allows you to pull values from a single data source, specified by its label. Various ways of requesting values are supported, depending on how your application needs to limit the amount of data returned.
GET /values/:label/last?count=:count¶
Get the last count values for a given data source, ordered by their timestamp, newest data first. The actual amount of data returned might be less than the count parameter. The default value for :count is 3 and the maximum is 100. This resource can be used for all data sources.
- Returns:
{ "count": 15, "data": [ { "timestamp": 1332971928.20006, "value": 132.0 } ] }
GET /values/:label/since?seconds=:seconds¶
Get the values from up to seconds ago for a given data source, ordered by their timestamp, newest data first. The first value returned might actually be from later than seconds ago. The default value for seconds is 3600 and the maximum is 7776000. This resource can be used for all data sources.
- Returns:
{ "count": 15, "data": [ { "timestamp": 1332971928.20006, "value": 132.0 } ] }
GET /values/:label/timespan?timespan=:timespan&timezone=:timezone¶
Get the last value for a series of periods for a given data source. The number of values returned depends on the timespan parameter. If a certain period is empty, meaning that no values from inside of it are found, the value returned for that period is null.
The allowed values for timespan are daily, weekly, monthly and yearly, with the default of monthly.
- daily is the last value of each hour from the last 24 hours
- weekly is the last value of each day from the last 7 hours
- monthly is the last value of each day from the last 30 days
- yearly is the last value of each month from the last 12 months
Each element of the returned data includes an addidional period field, thats an integer number of the period. For daily that would be the hour, from 0 to 23. For weekly, the the ISO weekday number, from 1 (Monday) to 7 (Sunday). For monthly, the day of the month, from 1 to 31. For yearly, the month number, from 1 to 12.
For each period, the timestamp field is the timestamp of the beginning of that period and the value field is the last value from that period. This resource can only be used with numeric data sources.
The limits of periods are actually dependent on the timezone parameter, as depending on which timezone you want to see the data in, the last value of each period might be different. See the example below for clarification. The default for timezone is UTC. For a list of allowed timezones, consult the Backgrounds, timezones, countries section in the Dashboard API documentation.
Apart from a value from each period, an additional structure with timestamp equal to null is added, containing the last value from before the beginning of the first period.
Here’s an example of how this resource works. Consider the following data:
| timestamp | value | ISO time in the UTC timezone |
|---|---|---|
| 1356048600 | 1 | 2012-12-21 00:10:00 |
| 1356135000 | 2 | 2012-12-22 00:10:00 |
| 1356307800 | 3 | 2012-12-24 00:10:00 |
Now let’s assume the current time is 1356480600, that is 2012-12-26 00:10:00 in UTC. A call like:
/values/:label/timespan?timespan=weekly&timezone=UTC
will return:
{
"count": 9,
"data": [
{
"timestamp": null,
"period": null,
"value": null
},
{
"timestamp": 1355875200.0,
"period": 3,
"value": null
},
{
"timestamp": 1355961600.0,
"period": 4,
"value": null
},
{
"timestamp": 1356048000.0,
"period": 5,
"value": 1.0
},
{
"timestamp": 1356134400.0,
"period": 6,
"value": 2.0
},
{
"timestamp": 1356220800.0,
"period": 7,
"value": null
},
{
"timestamp": 1356307200.0,
"period": 1,
"value": 3.0
},
{
"timestamp": 1356393600.0,
"period": 2,
"value": null
},
{
"timestamp": 1356480000.0,
"period": 3,
"value": null
}
]
}
The first actual item is the value from timestamp 1356048000, which is 2012-12-21 00:00:00 UTC. Note that the timestamp is 1356048000 (2012-12-21 00:00:00 UTC), even though the first data point stored is in 1356048600 (2012-12-21 00:10:00 UTC). That’s because each item is timestamped with the beginning of its period. The period field is 5, because 2012-12-21 is Friday. Also, observe how the value for timestamp 1356220800 (2012-12-23 00:00:00 UTC) is null. That’s because there is no original value for that period (Sunday 2012-12-23) and so null is returned.
Finally, the item with period and timestamp equal to null. That’s the value from before the first period returned. Since the first period is 1355875200 (2012-12-19 00:00:00 UTC) and there’s no data from before that time, the value for the null period is null.
All these calculations were done with the UTC timezone. To demonstrate how different the output would be, here’s an example in the America/Los_Angeles timezone:
/values/:label/timespan?timespan=weekly&timezone=America/Los_Angeles
will return:
{
"count" : 9,
"data" : [
{
"period" : null,
"timestamp" : null,
"value" : null
},
{
"period" : 2,
"timestamp" : 1355817600,
"value" : null
},
{
"period" : 3,
"timestamp" : 1355904000,
"value" : null
},
{
"period" : 4,
"timestamp" : 1355990400,
"value" : 1.0
},
{
"period" : 5,
"timestamp" : 1356076800,
"value" : 2.0
},
{
"period" : 6,
"timestamp" : 1356163200,
"value" : null,
},
{
"period" : 7,
"timestamp" : 1356249600,
"value" : 3.0
},
{
"period" : 1,
"timestamp" : 1356336000,
"value" : null
},
{
"period" : 2,
"timestamp" : 1356422400,
"value" : null
}
]
}
Note how the beginning of the first period is now 1355817600, which is 2012-12-18 08:00:00 UTC, which corresponds to 2012-12-18 00:00:00 in the America/Los_Angeles timezone - the beginning of Tuesday, 2012-12-18.
- Returns:
{ "count": 15, "data": [ { "timestamp": 1332971928.20006, "value": 132.0, "period": 13 } ] }