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, refer Version 4.0 - What's New?. The older version of Aggregate V3 will be available without any support and reduced quota till 30th June 2024.
Forming Aggregate V4 Request¶
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=4
-
New 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:
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"
}
]
The following response is returned for the Aggregate V4.x API:
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"
}
]
}
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
andaspectName
- If not provided by user, parameter
intervalValue
andintervalUnit
gets calculated automatically usingfrom
andto
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
- All query parameters are optional except
- 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
Except where otherwise noted, content on this site is licensed under the Development License Agreement.