Get aggregated time series data for one aspect of an asset.

GET {{baseUrl}}/aggregates?assetId=<string>&aspectName=<string>&from=<string>&to=<string>&intervalValue=<long>&intervalUnit=<string>&select=<string>&count=<string>

Returns a list of aggregates for a given asset and aspect. The time range of the aggregates can be defined by a combination of parameters; such as from, to, intervalUnit, intervalValue and count. Time range can be specified anywhere in past or future for which timeseries data is present. In the case no time series data was available for an aggregation interval, no aggregate will be returned. Pre-computed aggregates are aligned with the tenant's time zone.

Limitations - The maximum time range for querying DAY/WEEK/MONTH aggregates is 365 days. - The maximum time range for querying HOUR aggregates is 30 days. - The maximum time range for querying MINUTE aggregates is 48 hours.

Parameter Auto-Completion The parameters from, to, intervalUnit, intervalValue, and count are used to determine the time range and interval length to return aggregates for. Intelligent auto-completion is applied to allow clients to only provide a subset of the parameters, according to the following rules: 1. In case none of the parameters is provided, intervalUnit is set to DAY, intervalValue is set to 1, to is set to the current time, and from is set to the current time minus 7 days. 1. If only from is provided, to is set such that a 90 day time range results or, in case a larger range would result, to the current time. from is truncated to date-only for this calculation. 1. If only to is provided, from is set such that a 90 day time range results. 1. If intervalUnit, intervalValue and count are provided, it suffices to either provide to or from in addition. The missing parameter is determined based on the time range computed from intervalUnit, intervlValue and count. 1. If intervalUnit and intervalValue are not provided, the largest available interval length fitting into the used time range is chosen. 1. If count is not provided, but the other parameters are, count will be derived based on the time range divided by the intervalUnit and intervalValue. 1. In case parameters from or to are provided but do not coincide with the pre-calculated interval boundaries of the used interval, from and to are shifted such that the overall time range contains the provided one and time range boundaries coincide with interval boundaries. 1. If from, to and count are provided, intervalUnit, intervalValue is determined based on the time range divided by count.

Examples

Example 1: use of intervalUnit, intervalValue and count to derive end of time range.

A request with open time range is made

  from = 2019-02-01Z
  intervalUnit = day
  intervalValue = 1
  count = 7 

Rule 4 is applied to determine the 'to' parameter

  to = 2019-02-08Z

Example 2: time range auto-extension and count derivation.

A request with missing 'to' and 'count' parameters is made, and current system time is 2019-02-01T20:00:00Z

  from = 2019-02-01T10:00:00Z
  intervalUnit = hour
  intervalValue = 1

The 'to' time is derived based on Rule 2 to be the current time and 'count' is determined applying Rule 6

  to = 2019-02-01T20:00:00Z
  count = 10

Example 3: intervalUnit and intervalValue auto-completion.

A request without 'intervalUnit', 'intervalValue' and 'count' is made

  from = 2020-10-10T10:00:00Z
  to = 2020-10-10T10:30:00Z

Rule 5 is applied to determine the interval length based on the time range only. The count is derived based on rule 6 in the following.

  intervalUnit = minute
  intervalValue = 1
  count = 30

Example 4: intervalUnit and intervalValue auto-completion with larger interval

Similar as Example 3, a request without 'intervalUnit', 'intervalValue' and 'count' is made

  from = 2020-10-10T10:00:00Z
  to = 2020-10-10T12:00:00Z

Rules 5 and 6 are applied, but since the time range is multiple hours long, the interval is determined to be HOUR

  intervalUnit = hour
  intervalValue = 1
  count = 2

Example 5: intervalUnit and intervalValue auto-completion with much larger interval

Similar as Example 3 and 4, a request without 'intervalUnit', 'intervalValue' and 'count' is made

  from = 2020-10-10T00:00:00Z
 to = 2020-10-15T00:00:00Z

Rules 5 and 6 are applied, but since the time range is multiple days long, the interval is determined to be DAY

  intervalUnit = day
  intervalValue = 1
  count = 5

Example 6: intervalUnit and intervalValue auto-completion when count is also provided.

A request without 'intervalUnit' and 'intervalValue' is made

  from = 2020-10-10T10:00:00Z
  to = 2020-10-10T10:30:00Z
  count = 3

Since the difference between from and to date is 30 minute, and count asked is 3. Rule 8 is applied and 3 aggregate buckets of 10 minute is returned

  intervalUnit = minute
  intervalValue = 10

Example 7: to and from date adjusted to pre-computed aggregate boundary

Following request is made

 from = 2020-10-10T02:10:00Z
 to = 2020-10-10T09:10:00Z
 intervalUnit = hour
 intervalValue = 1

Rule 7 is applied since aggregate is queried for 1 hour and dates are not aligned to Hour boundary, *from* and *to* dates are adjusted to Hour boundary

from = 2020-10-10T02:00:00Z
to = 2020-10-10T10:00:00Z

Example 8: to, from, intervalUnit and intervalValue asking for 4 hour aggregate

Following request is made

 from = 2020-10-10T00:00:00Z
 to = 2020-10-11T00:00:00Z
 intervalUnit = hour
 intervalValue = 4

Since pre-computed aggregate exists for every HOUR, Hourly aggregates will be combined and a response bucket every 4 hours will be returned

Request Params

KeyDatatypeRequiredDescription
assetIdstring(Required) Unique identifier of the asset.
aspectNamestring(Required) Name of the aspect.
fromstringBeginning of the time range to read. ISO date format is supported with timezone. If no timezone is provided then it is considered as UTC aligned date-time. Example date time values are <table> <tr> <td>Date-time with no timezone provided</td> <td> 2020-02-20Z<br/> 2020-02-20T10Z<br/> 2020-02-20T10:30Z<br/> 2020-02-20T10:30:00Z<br/> 2020-02-20T10:30:00.000Z </td> </tr> <tr> <td>Date-time with timezone provided</td> <td> 2020-02-20-05:00<br/> 2020-02-20T10-05:00<br/> 2020-02-20T10:30-05:00<br/> 2020-02-20T10:30:00-05:00<br/> 2020-02-20T10:30:00.000-05:00 </td> </tr> </table>
tostringEnd of the time range to read. ISO date format is supported with timezone. If no timezone is provided then it is considered as UTC aligned date-time. Example date time values are <table> <tr> <td>Date-time with no timezone provided</td> <td> 2020-02-20Z<br/> 2020-02-20T10Z<br/> 2020-02-20T10:30Z<br/> 2020-02-20T10:30:00Z<br/> 2020-02-20T10:30:00.000Z </td> </tr> <tr> <td>Date-time with timezone provided</td> <td> 2020-02-20-05:00<br/> 2020-02-20T10-05:00<br/> 2020-02-20T10:30-05:00<br/> 2020-02-20T10:30:00-05:00<br/> 2020-02-20T10:30:00.000-05:00 </td> </tr> </table>
intervalValuestringInterval duration for the aggregates in intervalUnits. Supported values depends upon intervalUnit <br/> <table> <tr><td><b>intervalUnit</b></td><td><b>Supported intervalValue</b></td></tr> <tr><td>minute</td><td>1,2,3,4...59,60</td></tr> <tr><td>hour</td><td>1,2,3,4,...23,24</td></tr> <tr><td>day</td><td>1,2,3,4,...89,90</td></tr> <tr><td>week</td><td>1,2,3,4,...11,12</td></tr> <tr><td>month</td><td>1,2,3</td></tr> </table>
intervalUnitstringInterval duration unit for the aggregates. Supported values are <ul> <li>minute</li> <li>hour</li> <li>day</li> <li>week</li> <li>month</li> </ul>
selectstringIf this parameter is not provided all variables of aspect are returned in response. User can provide comma separated variables names in order to filter out variables. Variable names followed by '.' and aggregate field will return specific fields of aggregate object.<br/> Example 1- select=variable1,variable2 If above parameter provided in request, agregate response will only contain variable1 and variable2. <br/> Example 2- select=variable1.sum,variable2.sum If above parameter provided in request, agregate response will only contain variable1 and variable2 with only sum in aggregate response object.
countstringThis parameter is used to get number of aggregate objects in response.

HEADERS

KeyDatatypeRequiredDescription
Acceptstring

RESPONSES

status: OK

{&quot;aggregates&quot;:[{&quot;starttime&quot;:&quot;1951-11-28T03:11:21.576Z&quot;,&quot;endtime&quot;:&quot;1951-01-04T09:32:12.735Z&quot;,&quot;property1&quot;:{&quot;countgood&quot;:41915283,&quot;countuncertain&quot;:-12966873,&quot;countbad&quot;:8035618,&quot;sum&quot;:-8986340.753927723,&quot;average&quot;:67855181.0106968,&quot;mintime&quot;:&quot;1959-07-16T03:41:08.921Z&quot;,&quot;minvalue&quot;:38256338.62554279,&quot;maxtime&quot;:&quot;2012-01-11T17:05:56.728Z&quot;,&quot;maxvalue&quot;:13280360.942511752,&quot;firsttime&quot;:&quot;1953-02-07T17:27:13.493Z&quot;,&quot;firstvalue&quot;:83147811.0178372,&quot;lasttime&quot;:&quot;1957-08-27T06:36:05.110Z&quot;,&quot;lastvalue&quot;:47485063.82798678,&quot;sd&quot;:-67296758.93947613},&quot;property2&quot;:{&quot;countgood&quot;:61594897,&quot;countuncertain&quot;:-63957723,&quot;countbad&quot;:35187772,&quot;sum&quot;:-57346797.37027224,&quot;average&quot;:33989010.086980805,&quot;mintime&quot;:&quot;1990-08-16T09:08:58.257Z&quot;,&quot;minvalue&quot;:-77435778.16798633,&quot;maxtime&quot;:&quot;1988-06-14T14:32:29.209Z&quot;,&quot;maxvalue&quot;:34792344.505113125,&quot;firsttime&quot;:&quot;2021-08-04T15:20:12.393Z&quot;,&quot;firstvalue&quot;:-29496669.610460684,&quot;lasttime&quot;:&quot;1974-11-11T11:39:52.391Z&quot;,&quot;lastvalue&quot;:38596156.1743584,&quot;sd&quot;:3401298.4635798335}},{&quot;starttime&quot;:&quot;1957-01-13T21:29:12.554Z&quot;,&quot;endtime&quot;:&quot;1976-03-01T03:40:44.444Z&quot;,&quot;property1&quot;:{&quot;countgood&quot;:21585062,&quot;countuncertain&quot;:-83983195,&quot;countbad&quot;:83241570,&quot;sum&quot;:-44747037.22051015,&quot;average&quot;:-39919408.10419661,&quot;mintime&quot;:&quot;1990-12-18T21:16:24.683Z&quot;,&quot;minvalue&quot;:-56907304.94222085,&quot;maxtime&quot;:&quot;2021-04-03T21:06:39.145Z&quot;,&quot;maxvalue&quot;:92051982.03032699,&quot;firsttime&quot;:&quot;1975-09-15T21:19:21.899Z&quot;,&quot;firstvalue&quot;:64103572.20719752,&quot;lasttime&quot;:&quot;2022-01-06T04:38:06.119Z&quot;,&quot;lastvalue&quot;:-10614556.59013109,&quot;sd&quot;:-35871654.73335938},&quot;property2&quot;:{&quot;countgood&quot;:-88625819,&quot;countuncertain&quot;:80376491,&quot;countbad&quot;:-66138656,&quot;sum&quot;:93526793.61137787,&quot;average&quot;:1648728.1086229533,&quot;mintime&quot;:&quot;1991-06-19T11:35:37.093Z&quot;,&quot;minvalue&quot;:-84208430.6440547,&quot;maxtime&quot;:&quot;1944-12-20T10:17:54.522Z&quot;,&quot;maxvalue&quot;:73325664.78846708,&quot;firsttime&quot;:&quot;1992-09-20T17:26:43.833Z&quot;,&quot;firstvalue&quot;:24663590.088444605,&quot;lasttime&quot;:&quot;1952-05-17T05:57:47.032Z&quot;,&quot;lastvalue&quot;:-27234856.610229447,&quot;sd&quot;:-68000433.19989392}}]}