IoT Time Series Aggregates Service – Samples for v4.x¶

Requesting Aggregated Data¶

Performance Entity¶

In this example, there is an asset type forklift with an aspect tireMonitor and with the variables pressure, temperature, and treadDepth. The pressure variable has a quality code value of Y while the others are N. An instance of forklift with an asset ID of 978528e7a124458f87c8f1d38fd9400f is defined.

The following call requests data aggregated into 4 minute intervals from 2017-05-01T00:08:00Z until 2017-05-01T00:16:00Z for the tireMonitor aspect:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates?assetId=978528e7a124458f87c8f1d38fd9400f&aspectName=tireMonitor&from=2017-05-01T00:08:00Z&to=2017-05-01T00:16:00Z&select=pressure,temperature&intervalUnit=minute&intervalValue=4

The following response is returned for this request:

Response

{
  "aggregates":[
      {
          "pressure": {
              "firsttime": "2017-05-01T00:09:00Z",
              "average": 93.75,
              "lasttime": "2017-05-01T00:12:00Z",
              "maxvalue": 95,
              "firstvalue": 93,
              "mintime": "2017-05-01T00:10:00Z",
              "lastvalue": 94,
              "countgood": 4,
              "countuncertain": 0,
              "countbad": 0,
              "sum": 375,
              "minvalue": 93,
              "maxtime": "2017-05-01T00:11:00Z",
              "sd": 14.36
          },
          "temperature": {
              "firsttime": "2017-05-01T00:09:00Z",
              "average": 44.25,
              "lasttime": "2017-05-01T00:12:00Z",
              "maxvalue": 45,
              "firstvalue": 43,
              "mintime": "2017-05-01T00:09:00Z",
              "lastvalue": 44,
              "countgood": 4,
              "countuncertain": 0,
              "countbad": 0,
              "sum": 177,
              "minvalue": 43,
              "maxtime": "2017-05-01T00:11:00Z",
              "sd": 14.36
          },
          "starttime": "2017-05-01T00:08:00Z",
          "endtime": "2017-05-01T00:12:00Z"
      },
      {
          "pressure": {
              "firsttime": "2017-05-01T00:13:00Z",
              "average": 95,
              "lasttime": "2017-05-01T00:16:00Z",
              "maxvalue": 96,
              "firstvalue": 95,
              "mintime": "2017-05-01T00:15:00Z",
              "lastvalue": 96,
              "countgood": 4,
              "countuncertain": 0,
              "countbad": 0,
              "sum": 380,
              "minvalue": 94,
              "maxtime": "2017-05-01T00:16:00Z",
              "sd": 14.36
          },
          "temperature": {
              "firsttime": "2017-05-01T00:13:00Z",
              "average": 44.5,
              "lasttime": "2017-05-01T00:16:00Z",
              "maxvalue": 45,
              "firstvalue": 44,
              "mintime": "2017-05-01T00:14:00Z",
              "lastvalue": 44,
              "countgood": 4,
              "countuncertain": 0,
              "countbad": 0,
              "sum": 178,
              "minvalue": 43,
              "maxtime": "2017-05-01T00:15:00Z",
              "sd": 14.36
          },
          "starttime": "2017-05-01T00:12:00Z",
          "endtime": "2017-05-01T00:16:00Z"
      }
  ]
  }

Get Aggregate Data for a Specific Time Range with Select (variableName.fieldName) for Performance Entity¶

Specify the desired time range using the URL parameters from and to along with select average value:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates?assetId=978528e7a124458f87c8f1d38fd9400f&aspectName=tireMonitor&from=2017-05-01T00:08:00Z&to=2017-05-01T00:16:00Z&intervalUnit=minute&intervalValue=4&select=pressure.average,temperature.average

The following response is returned for this request

Response

{
"aggregates": [
  {
    "pressure": {
      "average": 93.75
    },
    "temperature": {
      "average": 44.25
    },
    "starttime": "2017-05-01T00:08:00Z",
    "endtime": "2017-05-01T00:12:00Z"
  },
  {
    "pressure": {
      "average": 95
    },
    "temperature": {
      "average": 44.5
    },
    "starttime": "2017-05-01T00:12:00Z",
    "endtime": "2017-05-01T00:16:00Z"
  }
]
}

Using "Select" will reduce the response size as per requirement and hence reduce the Read/Compute rate.

Defining Time Range and Interval Length¶

The following table lists the combinations of start time, end time, and interval length and explains the expected response:

Start Time	End Time	Interval Unit	Interval Value	Count	Explanation
2019-02-01Z		day	1	7	End time calculated using Interval Unit, Interval Value and count. End Time = (2019-02-01Z) + (1 day) * 7 = (2019-02-08Z)
2019-02-01T10:00:00Z		hour	1		Current system time is '2019-02-01T20:00:00Z', then End time calculated as End Time = 2019-02-01T20:00:00 and count = (End time - Start time) / Interval Length, i.e. (2019-02-01T20:00:00Z - 2019-02-01T10:00:00Z) / 1 hour = 10
2020-10-10T10:00:00Z	2020-10-10T10:30:00Z				Since the difference between Start Time and End time is less than 1 hour, Interval Length is calculated as '1 minute' with count = 30
2020-10-10T10:00:00Z	2020-10-10T12:00:00Z				Since the difference between Start Time and End time is more than 1 hour and less than 1 day, Interval Length is calculated as '1 hour' with count = 2
2020-10-10T00:00:00Z	2020-10-15T00:00:00Z				Since the difference between Start Time and End time is more than 1 day, Interval Length is calculated as '1 day' with count = 5
2020-10-10T10:00:00Z	2020-10-10T10:30:00Z			3	Since the difference between from and to date is 30 minute, and count asked is 3, Interval Length is calculated as '10 minute'
2020-10-10T02:10:00Z	2020-10-10T09:10:00Z	hour	1		Since aggregate is queried for 1 hour and dates are not aligned to Hour boundary, dates are adjusted to Hour boundary From = 2020-10-10T02:00:00Z and to = 2020-10-10T10:00:00Z
2020-10-10T00:00:00Z	2020-10-11T00:00:00Z	hour	4		Since pre-computed aggregate exists for every HOUR, Hourly aggregates will be combined and a response bucket every 4 hours will be returned

Get Day Aggregates with Date Range, timezone and Daylight Saving Time (DST)¶

Day aggregates are stored in asset's timezone.

Note

Daylight Saving Time (DST) has no impact on Pre-Calculated 1 Hour and 1 Minute aggregate as they are created in UTC timezone.*

Query when DST is OFF¶

If asset timezone is EST then day aggregates should be queried as mentioned below:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates/{assetId}/{aspectName}?from=2019-01-10T20:00:00Z&to=2019-01-12T20:00:00Z&intervalUnit=day&intervalValue=1

Since EST timezone is UTC-04:00, for querying day aggregates hour part should be mentioned as 20:00:00.

The same query can be done like this, specifying timezone information in query:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates/{assetId}/{aspectName}?from=2019-01-11T00:00:00-04:00&to=2019-01-13T00:00:00-04:00&intervalUnit=day&intervalValue=1

If a proper hour portion is not provided, then the service will automatically align dates to nearest Day boundary. For example:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates/{assetId}/{aspectName}?from=2019-01-10T00:00:00Z&to=2019-01-12T00:00:00Z&intervalUnit=day&intervalValue=1

Since asset's timezone is EST and in query we have not aligned timestamp, above query will be automatically aligned to this:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates/{assetId}/{aspectName}?from=2019-01-09T20:00:00Z&to=2019-01-12T20:00:00Z&intervalUnit=day&intervalValue=1

Query when DST is ON¶

When querying a Date Range where DST is ON:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates/{assetId}/{aspectName}?from=2019-10-10T19:00:00Z&to=2019-10-12T19:00:00Z&intervalUnit=day&intervalValue=1

Since day light is ON in October month, EDT timezone is UTC-05:00, day aggregates hour part should be mentioned as 19:00:00.

Same query can be done like this, specifying timezone information in query:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates/{assetId}/{aspectName}?from=2019-01-11T00:00:00-05:00&to=2019-01-13T00:00:00-05:00&intervalUnit=day&intervalValue=1

If proper hour portion is not provided the service will automatically align dates to nearest Day boundary. For example:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates/{assetId}/{aspectName}?from=2019-10-10T00:00:00Z&to=2019-10-12T00:00:00Z&intervalUnit=day&intervalValue=1

Since asset's timezone is EST (DST is ON) and in query we have not aligned timestamp, above query will be automatically aligned to this:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v4/aggregates/{assetId}/{aspectName}?from=2019-10-09T19:00:00Z&to=2019-10-12T19:00:00Z&intervalUnit=day&intervalValue=1

Query when DST is ON for start date and OFF for end date¶

When querying a Date Range where start date falls when DST is ON and end date falls when DST if OFF

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/{assetId}/{aspectName}?from=2019-10-10T19:00:00Z&to=2019-11-10T20:00:00Z&intervalUnit=day&intervalValue=1

Since day light is ON in October month, EDT timezone is UTC-05:00, day aggregates hour part should be mentioned as 19:00:00 for Start Date. Since day light is OFF in November month, EST timezone is UTC-04:00, day aggregates hour part should be mentioned as 20:00:00 for End Date.