This guide will help you to use the Ingestion API of the installed RENergetic system. This API allows you to insert time series data into the system. Provided data is validated against some requirements and saved only after successful validation. The API has 2 endpoints: one for data ingestion and one that returns requirements that data has to meet. For the API endpoints documentation see this page: RENergetic_API. An explanation of the data elements (measurements, fields and tags) can be found here: Measurements_Configuration.
Like other APIs, it have an application.properties file with the service configuration
That files allow to configure:
If this file is changed, the API should be deployed to apply the changes
Before data ingestion you can check the requirements that the sent message has to meet with the query below.
api/requirements
GET
{
"requestSize": 1000,
"measurements": [
"renewability",
"heat_pump",
"energy_meter",
"pv",
...
],
"tags": {
"prediction_window": [ null ],
"asset_name": [ null ],
"type_data": [
"real",
"simulated",
"forecasting"
]
...
},
"fields": [
{
"name": "power_w",
"type": "DOUBLE",
"format": null
},
{
"name": "temperature",
"type": "DOUBLE",
"format": null
},
{
"name": "energy_kwh",
"type": "DOUBLE",
"format": null
},
...
]
}
In order to ingest data into the RENergetic system, you have to make a POST request to the "{YOUR_FRONTEND_URL}/api-ingestion/1.0/api/ingest" path and provide a data point list as a request body. Each data point is a value with a timestamp and some metadata assigned to it.
The request below demonstrates the ingestion of the energy consumption values from 2 buildings ("building1" and "building2") at 2024-01-01 00:00:00.
Request:
[
{
"measurement": "energy_meter",
"fields": {
"time": "2024-01-01 00:00:00",
"energy_kwh": 1000
},
"tags": {
"asset_name": "building1",
"direction": "in",
"domain": "electricity",
"measurement_type": "energy",
"type_data": "real"
}
},
{
"measurement": "energy_meter",
"fields": {
"time": "2024-01-01 00:00:00",
"energy_kwh": 2000
},
"tags": {
"asset_name": "building2",
"direction": "in",
"domain": "electricity",
"measurement_type": "energy",
"type_data": "real"
}
}
]
Response:
{
"inserted": 2,
"errors": []
}
The API response indicates that 2 data points were inserted successfully.
The request below is the same request as in the previous example but with typos in tag and measurement names (marked in bold font) that make them incorrect.
Request:
[
{
"measurement": "energy_meter",
"fields": {
"time": "2024-01-01 00:00:00",
"energy_kwh": 1000
},
"tags": {
"asset_nam": "building1",
"direction": "in",
"domain": "electricity",
"measurement_type": "energy",
"type_data": "real"
}
},
{
"measurement": "energy_mete",
"fields": {
"time": "2024-01-01 00:00:00",
"energy_kwh": 2000
},
"tags": {
"asset_name": "building2",
"direction": "in",
"domain": "electricity",
"measurement_type": "energy",
"type_data": "real"
}
}
]
Response:
{
"inserted": 0,
"errors": [
{
"measurement": "energy_meter",
"fields": {
"time": "2024-01-01 00:00:00",
"energy_kwh": 1000
},
"tags": {
"asset_nam": "building1",
"direction": "in",
"domain": "electricity",
"measurement_type": "energy",
"type_data": "real"
},
"error": "Invalid tag name or value: 'asset_nam' isn't a valid tag name"
},
{
"measurement": "energy_mete",
"fields": {
"time": "2024-01-01 00:00:00",
"energy_kwh": 2000
},
"tags": {
"asset_name": "building2",
"direction": "in",
"domain": "electricity",
"measurement_type": "energy",
"type_data": "real"
}
"error": "Invalid measurement name: energy_mete"
}
]
}
The API response indicates that no data point was inserted successfully. The "errors" list contains 2 entries, each corresponding to an erroneous request. In case of the first point, the error message "Invalid tag name or value: 'asset_nam' isn't a valid tag name" indicates that the name of the tag "asset_nam" is not correct. The reason is that the allowed tag names returned by the requirements request didn’t contain the key "asset_nam". Similarly for the second point, the error message "Invalid measurement name: energy_mete" means that "energy_mete" is not allowed name of the measurement, because it was not listed in the measurement list of the requirements.