Skip to content

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.

Last update: September 9, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.