property.aggregate
The property.aggregate command is used to obtain historical property data aggregated over a specified time period for a thing. For more information about properties, see Understanding properties.
The Property aggregation occurs for properties that have the Calculate aggregates field set to true in the Thing Definition. For more information on properties of thing definitions, see Defining Properties and thing_def.create.
// Definite time period request
{
"cmd": {
"command": "property.aggregate",
"params": {
"thingKey": "mything",
"key": "myprop",
"calc": "avg",
"series": "day",
"start": "2020-01-01T00:00:00Z",
"end": "2020-01-31T23:59:59Z"
}
}
}
// Last period of time request
{
"cmd": {
"command": "property.aggregate",
"params": {
"thingKey": "mything",
"key": "myprop",
"calc": "avg",
"series": "hour",
"last": "8h"
}
}
}
Request Parameters
Name | Type | Required | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
thingId | String | Yes* | Id of the thing. | ||||||||||
thingKey | String | Key of the thing. | |||||||||||
esn | String | ESN of the thing. | |||||||||||
iccid | String | ICCID of the thing. | |||||||||||
imei | String | IMEI of the thing. | |||||||||||
imsi | String | IMSI of the thing. | |||||||||||
meid | String | MEID of the thing. | |||||||||||
*One of the above parameters is required to identify the thing. If omitted, the thingKey associated with your session will be used. | |||||||||||||
key | String | Yes | The key for the property that you wish to aggregate. | ||||||||||
calc | String | Yes |
Way to calculate aggregation:
For more details on data aggregation, see Data Aggregation. Below is an example of property published during the 10:00 hour:
In this example, the average calculations are as follows for the 10:00 hour:
|
||||||||||
series | String | Yes | The series to be used when grouping property values to aggregate.. hour or day are the values that is assigned to the series. For more details on data aggregation, see Data Aggregation. | ||||||||||
start | String | Timestamp for the start of the specified time window. | |||||||||||
end | String | Timestamp for the end of the specified time window. | |||||||||||
last | String | When doing a last period of time request this specifies the last X amount of time in nanoseconds (ns), microseconds (us), milliseconds (ms), seconds (s), minutes (m) or hours (h). | |||||||||||
split | Bool | Set to true if you want the timestamp and value fields to be split into two arrays. |
If the command is sent successfully a success message and the property values found are returned. Otherwise, an error and error message will be returned.
The number of records returned is limited to 5000 by the deviceWISE Cloud. If your query returns more results than the limit of the deviceWISE Cloud, you should shorten your time window or lower the number of records you are requesting.
{
"cmd": {
"success": true,
"params": {
"values": [
{
"value": 40,
"ts": "2020-01-01T01:01:01Z"
},
{
"value": 41,
"ts": "2020-01-02T01:11:02Z"
},
{
"value": 39,
"ts": "2020-01-03T01:22:01Z"
}
]
}
}
}
// "split" response example
{
"cmd": {
"success": true,
"params": {
"values": [
40,
41,
39
],
"timestamps": [
"2020-01-01T01:01:01Z",
"2020-01-02T01:11:02Z",
"2020-01-03T01:22:01Z"
]
}
}
}
Response Parameters
The property.aggregate response can be either:
- Values array with the following parameters
Name | Type | Description |
---|---|---|
value | Integer | The value for the given timestamp |
ts | String | Timestamp for the given value |
- Two arrays: values & timestamps when the split request parameter is set to true
Name | Type | Description |
---|---|---|
values | Array | Array of values |
timestamps | Array | Array of timestamps |
The property.aggregate response can also contain the following key:
Name | Type | Description |
---|---|---|
truncated | Boolean | If this value is in the response, it will be true. It is defined if the number of possible records is equal to or greater than the maximum configured. |
PHP API
mixed TR50httpWorker::propertyAggregate($thingKey, $key, $calc, $series, $start, $end[, $split]);