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 timestamp is not aligned in query, the above query will be automatically aligned like the following:
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 timestamp is not aligned in query, the 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.
The same query can be done like this, specifying timezone information in query:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/{assetId}/{aspectName}?from=2019-10-11T00:00:00-05:00&to=2019-11-11T00:00:00-04: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/v3/aggregates/{assetId}/{aspectName}?from=2019-10-10T00:00:00Z&to=2019-11-10T00:00:00Z&intervalUnit=day&intervalValue=1
Since asset's timezone is EST (Start time is in DST and End time is outside DST) and timestamp is not aligned in query, above query will be automatically aligned to this:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/{assetId}/{aspectName}?from=2019-10-09T19:00:00Z&to=2019-11-10T20:00:00Z&intervalUnit=day&intervalValue=1
Except where otherwise noted, content on this site is licensed under the Development License Agreement.