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

[
    {
        "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 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:

[
    {
        "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¶