IoT Time Series Aggregates Service – V3.x to V4.x Migration Guide¶
Announcement
For more information about new features and limitations for Aggregate V4 API, please refer Version 4.0 - What's New?. Older version of Aggregate V3 will be available without any support & reduced quota till 30th June'2024.
Forming Aggregate V4 Request¶
Let us consider an example, where 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.
Existing Aggregate V3.x URL:
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=4New Aggregate V4.x URL:
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
There are differences in response which are mentioned below:
The following response is returned for the Aggregate V3.x API:
```json
[
{
"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"
}
]
```
The following response is returned for the Aggregate V4.x API:
```json
{
"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"
}
]
}
```
Related links¶
FAQs¶
- Why should I migrate to V4?
Aggregate v4 API centers around improved usability through advanced intelligent features and new functionalities such as:- All query parameters are optional except assetId and aspectName
- If not provided by user, parameter intervalValue and intervalUnit gets calculated automatically using from and to date
- Added new parameter count to specify the number of aggregates a user needs
- Asset and Aspect ids as query parameter
- Support for ISO date formats
- Removed limit on records and added limits on duration and number of calls
- Is there any difference between v3 and v4 API?
Yes there are below mentioned differences:- Any value of interval is not supported but aggregates are now available where user just needs to specify time range based on which optimal intervals are auto selected by the system to provide response swiftly.
- There is no limitations of 200 records in new V4 API as compared to V3 API
- Enhanced ISO date format is now supported in Aggregate V4 APIs
- Simulation asset is not supported on Aggregate V4 API