Guide to Multi-stage Aggregations Time Series Data API Endpoint (Conduit V7)

Overview

This guide provides detailed support for the API endpoint that supports multi-stage aggregations for time series data. By using this endpoint, users can retrieve aggregated time series data for various sensors in JSON format.

Introduction

In today’s digital age, having the ability to process and interpret large volumes of data is crucial. With our Multi-Stage Data Aggregation API, you can do just that, and with greater precision than ever before. This API stands out by providing up to 4 stages of data aggregation tailored to your specific requirements.

Pre-requisites

Before you can access the API endpoint, ensure that:

• You have a valid token for authentication.
• If you haven’t activated your token yet, please refer to [this help article](http://52.147.34.237/knowledge-base/how-to-enable-conduit-for-a-user/) on how to enable Conduit for a user

Core Features:

Aggregation Methods:

You can select from one of the following aggregation outputs:

• Count
• Sum
• Average
• Maximum
• Minimum
• Range
• Difference
• Cumulative

Aggregation Groupings:

The above aggregations can be grouped by the following:

• Minutes
• Hours
• Days
• Weeks
• Months
• Years

Pre-Stages of Aggregation:

This powerful feature lets you pre-process your data with preliminary aggregations before they are processed in the primary output. These aggregations have the same options as the primary output, which means you can apply multiple layers of aggregation to produce the most relevant insights.

Practical Examples:

To better understand the functionality and practicality of this tool, let’s delve into some real-world operational scenarios:

Energy Management:

• Use cumulative aggregation grouped by days to track energy consumption over time.
• Pre-stage with an average aggregation by hours to identify average energy usage for the period cumulated.

Occupancy Data:

• Use count aggregation grouped by weeks to find out the number of visitors per week.
• Pre-stage with maximum aggregation by hours to determine the maximum number of occupants over the week.

Meteorology Data:

• Use range aggregation grouped by months to identify monthly temperature fluctuations.
• Pre-stage with average aggregation by days to understand daily temperature trends within those months.

These applications are just a glimpse of what’s achievable with the Multi-Stage Data Aggregation API. Depending on your needs, this tool can be tailored to deliver precise and actionable insights and only limited by your creativity.

API Parameters

• When timerange Applied and Valid, return the data from last timerange seconds.

• When timerange Not Applied or Invalid and fcdt & tcdt Applied and Valid, return the data from fcdt to tcdt.

• Otherwise return the data from last 1 hour.

Aggregation Parameters

When Multi-stage Aggregation parameters Applied, Aggregation is the Last stage;

When Multi-stage Aggregation parameters Not Applied, Aggregation is the Only stage;

For group parameter, the time range of Previous Stage must be Shorter. For example, If groupby is ‘hour’, pregroup1 must be ‘minute’ and pregroup2 & 3 and preaggregate2 & 3 cannot be applied. Other wise the data won’t be accurate.

Data Format

The response from the API will be in the JSON format. Below is the structure of the data you will receive:
[
{
"channelDescription": "",
"id": "",
"chid": "",
"netid": "",
"data": [
{"timestamp": "", "value": ""}
],
"deviceName": "",
"labelColor": "",
"labelName": "",
"location": "",
"locationSensor": "",
"tag": "",
"unit": "",
"timezone": "",
"siteid": "",
"sensorType": "",
"limitData": "",
"limitOutput": "",
"cal": "",
"offset": "",
"maxVal": "",
"minVal": ""
}
]

Field Descriptions

• channelDescription: Description of the channel.
• id: Unique identifier for the sensor.
• chid: Channel identifier.
• netid: Network identifier.
• data: Array of data points, each containing a timestamp and value.
• deviceName: Name of the device.
• labelColor: Color assigned to the label.
• labelName: Name of the label.
• location: Information about the location of sensors.
• locationSensor: Location sensor information for virtual channels.
• tag: Tag related to the device.
• unit: Measurement unit of the data.
• timezone: The timezone in which the data is represented.
• siteid: Entity identifier.
• sensorType: Type of sensor.
• limitData: Indicates if the input record limit has been reached (maximum of 843000 datapoints).
• limitOutput: Indicates if the request data limit has been reached (maximum of 105120 datapoints).
• cal: Data calibration factor.
• offset: Data calibration offset.
• maxVal: Maximum data value.
• minVal: Minimum data value.

Common Issues & Troubleshooting

1. Authentication Error: If you receive an authentication error, ensure that you are using a valid token. If you have not activated your token, refer to the above-mentioned help article.
2. Data Limit Reached:
   • If limitData returns true, you have reached the maximum record input limit. Consider filtering or reducing the amount of data you are sending.
   • If limitOutput returns true, you have reached the maximum request data limit. Consider requesting data in smaller batches or within a narrower timeframe.
3. Data Inconsistencies: If the data seems inconsistent or doesn’t match expected values, check the cal and offset values. These represent calibration factors and offsets applied to the data.
4. Timezone Issues: Ensure that the timezone field matches your expected timezone, as it can impact the interpretation of timestamp values in the data.
5. No Data Received: If you do not receive any data, ensure that your request parameters (such as date ranges, sensor ids, etc.) are correctly set.

Examples

To better assist you in utilising the API endpoint, here are a few examples:

1. Get hourly sum from all channels of device cos-cam-010 in a time range:

https://app.alphax.cloud/conduitv7?token=xxxxxxxxxxxxxxxxxxxx&fcdt=xxxxxxxxxx&tcdt=xxxxxxxxxx&id=cos-cam-010&groupby=hour&aggregateby=sum

2. **Get hourly sum from channel 1 of device cos-cam-010 in a time range**:

https://app.alphax.cloud/conduitv7?token=xxxxxxxxxxxxxxxxxxxx&fcdt=xxxxxxxxxx&tcdt=xxxxxxxxxx&id=cos-cam-010&ch=1&groupby=hour&aggregateby=avg

3. **Get raw data from all devices of an entity in the last 1 hour**:

https://dev.alphax.cloud/getHourlyData?token=xxxxxxxxxxxxxxxxxxxx&siteid=xxxxxxxxxxxxxxxxxx

4. **Get daily range of hourly average from all devices of the entity that the token is assigned to in a time range**:

https://app.alphax.cloud/conduitv7?token=xxxxxxxxxxxxxxxxxxxx&siteid=xxxxxxxxxxxxxxxxxx&fcdt=xxxxxxxxxx&tcdt=xxxxxxxxxx&aggregateby=range&groupby=day&preaggregate1=avg&pregroup1=hour

How to Use The Examples

1. Replace `xxxxxxxxxxxxxxxxxxxx` with your valid token.
2. Replace `xxxxxxxxxx` in `fcdt` and `tcdt` with your desired start and end time respectively in 10 digit unix timestamp format.
3. If you are accessing data for a specific entity, replace `xxxxxxxxxxxxxxxxxx` in `siteid` with your entity ID. Support Article here:  http://52.147.34.237/knowledge-base/how-to-find-the-id-of-an-entity-in-alphax/ 

These examples provide a starting point and can be modified based on your specific requirements. Always ensure that you are using the correct parameters and their values for successful data retrieval.

Support Contact

If you’re facing issues not covered in this guide or need further assistance, please contact our support team at [email protected] or visit our knowledge base for more information.