property.aggregate

Property aggregation occurs for properties that have the calcAggregates field in the property definition of the thing definition set to true. For more information on properties of thing definitions, see Defining Properties and thing_def.create.

Property aggregates can be calculated using the following values:

You can also select the series returned for the time period in hourly or daily grouping.

The following describes the differences between the avg, wavg and nzwavg calculations and the appropriate use of each: 

• The avg calculation is determined by taking the sum of all publishes during the time period divided by the number of publishes during that period.

  • Example: Torque values when tightening a bolt should be averaged, as each torque measurement is not related to the time between the measurements.

• The wavg calculation is determined by weighting each publish for the number of minutes that it is the current value in the time period.

  • Example: Power usage in a location should be tracked using a weighted average to determine the power usage over a given period of time.

• The nzwavg calculation is determined similarly to the wavg, except that instead of weighting across the entire time period in the series (one hour or one day), it is calculated against the time in the period the value was non-zero.

  • Example: Calculating the average speed of a vehicle should use nzwavg so you only calculate the average speed while the vehicle is moving (do not include the time when the vehicle is stopped).

The following shows an example of property published during the hour starting at 10:00:

In this example, the average calculations for the time period are as follows:

• avg: 125

• wavg: 100

• nzwavg: 150

TR50 Request

// Definite time period request
{
  "cmd": {
    "command": "property.aggregate",
    "params": {
      "thingKey": "mything",
      "key": "myprop",
      "calc": "avg",
      "series": "day",
      "start": "2014-01-01T00:00:00Z",
      "end": "2014-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

Thing Identifier Parameters

TR50 Response

If the command is sent successfully a success message and the property values found are returned. Otherwise, an error and error message are returned.

The number of records returned is limited by the Management Portal. In cases where your selection has more results than the limit of the platform, shorten your time window or lower the number of records you are requesting.

{
  "cmd": {
    "success": true,
    "params": {
      "values": [
        {
          "value": 40,
          "ts": "2014-01-01T01:01:01Z"
        },
        {
          "value": 41,
          "ts": "2014-01-02T01:11:02Z"
        },
        {
          "value": 39,
          "ts": "2014-01-03T01:22:01Z"
        }
      ]
    }
  }
}
 
// "split" response example
{
  "cmd": {
    "success": true,
    "params": {
      "values": [
        40,
        41,
        39
      ],
      "timestamps": [
        "2014-01-01T01:01:01Z",
        "2014-01-02T01:11:02Z",
        "2014-01-03T01:22:01Z"
      ]
    }
  }
}
      

Response Parameters

The property.aggregate response can be either:

• Values array with the following parameters

• Two arrays: values and timestamps when the split request parameter is set to true

The property.aggregate response can also contain the following key: