IoT Time Series Aggregates Service – Samples¶
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:00 until 2017-05-01T00:16:00Z for the tireMonitor aspect:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/978528e7a124458f87c8f1d38fd9400f/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
[
{
"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/v3/aggregates/{{entityId}}/{{propset}}?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:
[
{
"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.
Get Aggregate Data for a Specific Time Range with Time Zone for Performance Entity¶
Specify the desired time range using the URL parameters from and to:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/{assetId}/{aspectName}?from=2017-05-01T00:08:00%2B02:00&to=2017-05-01T00:16:00%2B02:00&intervalUnit=minute&intervalValue=4
For setting the time zone of the time range, the + character must be encoded to %2B in the URL. For example, 2017-05-01T00:08:00%2B02:00 instead of 2017-05-01T00:08:00+02:00.
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 specified below:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/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, the hour part should be mentioned as 20:00:00.
Same query can be done as mentioned below, by specifying timezone information in query.
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/{assetId}/{aspectName}?from=2019-01-11T00:00:00-04:00&to=2019-01-13T00:00:00-04:00&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/v3/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 as mentioned below by specifying timezone information in query:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/{assetId}/{aspectName}?from=2019-01-11T00:00:00-05:00&to=2019-01-13T00:00:00-05:00&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.
Same query can be done as mentioned below, by specifying timezone information in the 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
Simulation Entity¶
The following call requests data aggregated into 1 millisecond intervals from 2017-05-01T00:08:00.001 until 2017-05-01T00:08:00.003Z for the tireMonitor aspect:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/978528e7a124458f87c8f1d38fd9400f/tireMonitor?from=2017-05-01T00:08:00.001Z&to=2017-05-01T00:08:00.003Z&select=pressure,temperature&intervalUnit=millisecond&intervalValue=1
The following response is returned for this request:Response
[
{
"pressure": {
"firsttime": "2017-05-01T00:08:00.001015Z",
"average": 93.75,
"lasttime": "2017-05-01T00:08:00.001018Z",
"maxvalue": 95,
"firstvalue": 93,
"mintime": "2017-05-01T00:08:00.001016Z",
"lastvalue": 94,
"countgood": 4,
"countuncertain": 0,
"countbad": 0,
"sum": 375,
"minvalue": 93,
"maxtime": "2017-05-01T00:08:00.001017Z",
"sd": 14.36
},
"temperature": {
"firsttime": "2017-05-01T00:08:00.001015Z",
"average": 44.25,
"lasttime": "2017-05-01T00:08:00.001018Z",
"maxvalue": 45,
"firstvalue": 43,
"mintime": "2017-05-01T00:08:.001012Z",
"lastvalue": 44,
"countgood": 4,
"countuncertain": 0,
"countbad": 0,
"sum": 177,
"minvalue": 43,
"maxtime": "2017-05-01T00:08:00.001019Z",
"sd": 14.36
},
"starttime": "2017-05-01T00:08:00.001Z",
"endtime": "2017-05-01T00:08:00.002Z"
},
{
"pressure": {
"firsttime": "2017-05-01T00:08:00.002015Z",
"average": 95,
"lasttime": "2017-05-01T00:08:00.2018Z",
"maxvalue": 96,
"firstvalue": 95,
"mintime": "2017-05-01T00:08:00.002010Z",
"lastvalue": 96,
"countgood": 4,
"countuncertain": 0,
"countbad": 0,
"sum": 380,
"minvalue": 94,
"maxtime": "2017-05-01T00:08:00.002019Z",
"sd": 14.36
},
"temperature": {
"firsttime": "2017-05-01T00:08:00.002014",
"average": 44.5,
"lasttime": "2017-05-01T00:08:00.2018Z",
"maxvalue": 45,
"firstvalue": 44,
"mintime": "2017-05-01T00:08:00.002010Z",
"lastvalue": 44,
"countgood": 4,
"countuncertain": 0,
"countbad": 0,
"sum": 178,
"minvalue": 43,
"maxtime": "2017-05-01T00:08:00.002011Z",
"sd": 14.36
},
"starttime": "2017-05-01T00:08:00.002Z",
"endtime": "2017-05-01T00:08:00.003Z"
}
]
Get Aggregate Data for a Specific Time Range with Time Zone for Simulation Entity¶
Specify the desired time range using the URL parameters from and to:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottsaggregates/v3/aggregates/{assetId}/{aspectName}?from=2017-05-01T00:08:00.001%2B02:00&to=2017-05-01T00:08:00.003%2B02:00&intervalUnit=millisecond&intervalValue=1
For setting the time zone of the time range, the + character must be encoded to %2B in the URL. For example, 2017-05-01T00:08:00.001%2B02:00 instead of 2017-05-01T00:08:00.001+02:00.
Defining Start Time and Time Range¶
As described in Requesting Aggregates, the start and end times cannot be defined with higher precision than the time range. For clarification, the following table lists combinations of start time, end time, and interval length and explains the expected response:
| Start Time | End Time | Interval Length | Returned Intervals | Explanation |
|---|---|---|---|---|
| 14:00:01.000 | 14:00:01.300 | 1 ms | - | Rejected since the response would contain more than 200 intervals. Interval length available for simulation entities only. |
| 14:00:01.005 | 14:00:01.015 | 10 ms | - | Rejected since start and end time defined with higher precision than interval length. Interval length available for simulation entities only. |
| 14:00:01.000 | 14:00:02.000 | 1 second | 1 | Interval length available for simulation entities only. |
| 14:00 | 15:00 | 1 minute | 60 | Interval length available for performance entities only. |
| 14:00 | 15:00 | 4 minute | 15 | Interval length available for performance entities only. |
| 14:00 | 15:00 | 2 minute | 30 | Calculated from pre-calculated intervals and time series data. Interval length available for performance entities only. |
| 14:00 | 15:00 | 3 minute | 20 | Calculated from pre-calculated intervals and time series data. Interval length available for performance entities only. |
| 14:01 | 15:01 | 2 minute | 30 | Calculated on the fly from raw time series data. Interval length available for performance entities only. |
| 14:30 | 16:30 | 1 hour | - | Rejected - start and end times defined with higher precision than interval length |
| 14:30 | 16:30 | 60 minute | 2 | Interval length available for performance entities only. |
| 14:30 | 16:30 | 30 minute | 4 | Interval length available for performance entities only. |
| March 1st, 00:00 | March 5th, 00:00 | 1 day | - | Rejected - start and end times defined with higher precision than interval length Interval length available for performance entities only. |
| March 1st, 00:00 | March 5th, 00:00 | 24 h | 4 | Interval length available for performance entities only. |
| March 1st (Wednesday), 00:00 | April 1st, 00:00 | 1 week | - | Rejected - start and end times defined with higher precision than interval length (assuming weeks start on Monday for this environment) Interval length available for performance entities only. |
| March 1st, 00:00 | April 5th, 00:00 | 7 day | 5 | Interval length available for performance entities only. |
| March 1st, 00:00 | June 1st, 00:00 | 1 month | 3 | Interval length available for performance entities only. |
| March 1st, 00:00 | June 29th, 00:00 | 30 day | 4 | Interval length available for performance entities only. |