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.

TR50 Request

// 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:

avg - The average within the specified time period.
wavg - The time weighted average within the specified time period.
nzwavg - The non-zero time weighted average within the specified time period.
sum - The sum of the property values within the specified time period.
max - The maximum property value within the specified time period.
min - The minimum property value within the specified time period.
count - The count of the property values within the specified time period.

For more details on data aggregation, see Data Aggregation.

Below is an example of property published during the 10:00 hour:

Example	Value
10:00	100
10:20	200
10:30	0
10:50	200

In this example, the average calculations are as follows for the 10:00 hour:

avg: 125
wavg: 100
nzwavg: 150

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.

TR50 Response

{
  "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]);