Telemetries Data

Aggregated APIs

Aggregated APIs are mainly used when you want to obtain, for a certain type of data, a single value in response, which allows to summarize a certain trend and/or result, for a customized time window.

These type of APIs are always structured as follows:

The path, which allows you to point to the desired resources, always requires the following parameters:

• {power,frequency,wind,temperature,voltage,current,energy,kpis}: the type of resource to point to. This parameter does not specify the actual data you want to obtain, but the general category to which the desired data belongs (please note that an API call only accepts one category at a time, it is not currently possible to make BULK calls);
• {entityID}: it can be a plant or a device EID. In the first case, the value obtained takes into account the aggregation of all the devices, for which that value exists, at the plant level; in the second case, the value obtained referred to the single device of interest;
• {dataType}: represents the actual data to be obtained. The available dataTypes vary according to the resources pointed at, a detailed description is available directly in the OpenAPIs Swagger;
• {valuetype}: represents the type of aggregation criterion with which the requested data is to be obtained.

The queries, that allow you to filter the requested data, always require the following parameters:

• {startDate}: the lower-bound that allows to define the beginning of the time window of interest. Its format is always YYYYMMGG (eg: 20220321);
• {endDate}: the upper-bound which allows to define the end of the time window of interest. Its format is always YYYYMMGG (eg: 20220322) and it must be temporally subsequent to the {startDate};
• {timezone}: allows to guide the API call to a correct data recovery according to the requested time zone.

An aggregate call always provides a single value as response, which is manipulated according to the time window and the time zone indicated. In this context, the {valuetype} parameter is of great importance because it varies according to the category of resources, therefore of {dataType}, to be obtained.

For a {dataType} belonging to the category {power,frequency,wind,temperature,voltage,current,kpis}, the {valueType} can assume three different values:

• Maximum: returns the maximum value found among all the samples present in the defined {startDate} and {endDate} time window, for the requested {dataType};
• Minimum: returns the minimum value found among all the samples present in the defined {startDate} and {endDate} time window, for the requested {dataType};
• Average: returns the average value of all the samples present in the defined {startDate} and {endDate} time window, for the requested {dataType};

---

NOTE: for the kpis category, the above considerations are valid only if Power-Based KPIs are called. For more details, please refer to OpenAPIs Swagger.

---

Let’s take a look at some use cases, where we consider a plant ( entityID: 12345678 ) with a single registered inverter device ( entityID : 87654321 ):

For a {dataType} belonging to the category {energy,kpis}, the {valueType} can assume two different values:

• Cumulative: returns the last cumulative value available in the defined {startDate} and {endDate} time window, for the requested {dataType};
• Delta: returns the difference between the last and the first cumulative value available in the defined {startDate} and {endDate} time window, for the requested {dataType};

---

NOTE: for the kpis category, the above considerations are valid only if Energy-Based KPIs are called. For more details, please refer to OpenAPIs Swagger.

---

Let’s take a look at some use cases, where we consider a plant ( entityID: 12345678 ) with a single registered inverter device ( entityID : 87654321 ):