Consumption calculation

The Energy Consumption Tracking APIs provide detailed insights into the energy usage of a site. These APIs support tracking consumption at various time intervals over a defined period, calculating consumption using available data, and interpolating when necessary. The APIs return information on energy consumption and cost for both electricity and gas, and CO2 emissions for electricity.

Data Sources and Calculation

Consumption is calculated using the following data sources for each type of energy:

Electricity: Consumption indexes and/or load curve data
Gas: Consumption indexes and volumes in cubic meters

In cases where sufficient data is not available to calculate the actual consumption, interpolation methods are used to accurately estimate consumption values.

Tracking Period and Time Step

The APIs allow to track consumption at different time intervals (e.g. yearly, monthly, daily) over a specified period. This flexibility ensures that users can monitor their energy consumption according to their specific needs.

Energy, Cost and Emissions Tracking

Electricity

The endpoint GET sites/{site-id}/consumptions provides a detailed report on a site consumption including:

Electricity Consumption: Total electricity consumption in kWh.
Cost: Total cost of the consumed electricity (with the details of standing charges)
CO2 Emissions: Equivalent CO2 emissions.
Tariff Heading Breakdown: Energy and cost are broken down according to the client’s contract tariff headings (e.g. peak hours or off-peak hours).

It is also possible to track electricity consumptions only by using load curve data via the endpoint GET consumptions/load-curve.

Examples

GET consumptions?beginTs=2022-12-31T23:00:00.00Z&stepUnit=months&filters=WITH_CARBON_FOOTPRINT,WITH_GLOBAL_CONSUMPTION,WITH_RATIO_BY_TARIFF_HEADING&endTs=2023-02-28T22:00:00.00Z

{
    "period": {
        "startTime": "2023-01-01T00:00:00+01:00",
        "endTime": "2023-02-28T23:00:00+01:00"
    },
    "step": "P1M",
    "units": {
        "cost": "EUR",
        "energyMeter": "KWH",
        "carbonFootprint": "KG"
    },
    "consumptions": [
        {
            "period": {
                "startTime": "2023-01-01T00:00:00+01:00",
                "endTime": "2023-02-01T00:00:00+01:00"
            },
            "energyMeter": {
                "total": 1873.034,
                "byTariffHeading": {
                    "HP": 1397.821,
                    "HC": 475.213
                }
            },
            "ratioByTariffHeading": {
                "HP": 0.746,
                "HC": 0.254
            },
            "ratioByTariffHeadingGroup": {
                "HP": 0.746,
                "HC": 0.254
            },
            "cost": {
                "total": 356.8868673408602,
                "standingCharge": 11.98602150537634,
                "standingChargeByComponents": {},
                "byTariffHeading": {
                    "HP": 273.0440414,
                    "HC": 71.85680443548388
                }
            },
            "carbonFootprint": {
                "coefficient": 0.057,
                "total": 106.762938
            },
            "quality": 1.0,
            "errorFlags": [],
            "indexNatures": [
                "LINKY_OK"
            ],
            "status": "COMPLETE",
            "nature": "REAL",
            "aggregated": false,
            "usingLoadCurve": false
        },
        {
            "period": {
                "startTime": "2023-02-01T00:00:00+01:00",
                "endTime": "2023-02-28T23:00:00+01:00"
            },
            "energyMeter": {
                "total": 1704.54008193757,
                "byTariffHeading": {
                    "HP": 1284.926,
                    "HC": 419.61408193757
                }
            },
            "ratioByTariffHeading": {
                "HP": 0.754,
                "HC": 0.246
            },
            "ratioByTariffHeadingGroup": {
                "HP": 0.754,
                "HC": 0.246
            },
            "cost": {
                "total": 365.9532941757748,
                "standingCharge": 11.90410714285715,
                "standingChargeByComponents": {},
                "byTariffHeading": {
                    "HP": 286.2815128,
                    "HC": 67.76767423291756
                }
            },
            "carbonFootprint": {
                "coefficient": 0.057,
                "total": 97.15878467044149
            },
            "quality": 1.0,
            "errorFlags": [],
            "indexNatures": [
                "LINKY_OK"
            ],
            "status": "COMPLETE",
            "nature": "REAL",
            "aggregated": true,
            "usingLoadCurve": true
        }
    ],
    "globalConsumption": {
        "period": {
            "startTime": "2023-01-01T00:00:00+01:00",
            "endTime": "2023-02-28T23:00:00+01:00"
        },
        "energyMeter": {
            "total": 3577.57408193757,
            "byTariffHeading": {
                "HP": 2682.747,
                "HC": 894.82708193757
            }
        },
        "ratioByTariffHeading": {
            "HP": 0.750,
            "HC": 0.250
        },
        "ratioByTariffHeadingGroup": {
            "HP": 0.750,
            "HC": 0.250
        },
        "cost": {
            "total": 721.8183092408392,
            "standingCharge": 23.89012864823349,
            "standingChargeByComponents": {},
            "byTariffHeading": {
                "HP": 558.3351558103448,
                "HC": 139.59302478226093
            }
        },
        "carbonFootprint": {
            "coefficient": 0.057,
            "total": 203.9217226704415
        },
        "quality": 1.0,
        "errorFlags": [],
        "indexNatures": [
            "LINKY_OK"
        ],
        "status": "COMPLETE",
        "nature": "REAL",
        "aggregated": true,
        "usingLoadCurve": true
    }
}

Gas

The endpoints GET /compositions/monthly-gas-consumptions and GET /smart-daily-gas-consumptions provide a detailed report on a site consumption including:

Gas Consumption: Total gas consumption in cubic meters and kWh.
Cost: Total cost of the consumed gas. (with the details of standing charges)

Examples

GET /compositions/monthly-gas-consumptions?begin-month=2023-06&end-month=2023-09

{
    "monthlyGasEnergies": [
        {
            "month": "2023-06",
            "beginDay": "2023-06-01",
            "endDay": "2023-07-01",
            "consumption": {
                "energy": 3261.177,
                "energyM3": 300.0,
                "conversionFactor": 10.871,
                "cost": 258.6113361
            },
            "standingCharge": 25.17290322580645,
            "totalCost": 283.7842393258065,
            "source": "SMART",
            "nature": "REEL"
        },
        {
            "month": "2023-07",
            "beginDay": "2023-07-01",
            "endDay": "2023-08-01",
            "consumption": {
                "energy": 3369.8829,
                "energyM3": 310.0,
                "conversionFactor": 10.871,
                "cost": 267.23171397
            },
            "standingCharge": 25.2309677419355,
            "totalCost": 292.4626817119355,
            "source": "SMART",
            "nature": "REEL"
        },
        {
            "month": "2023-08",
            "beginDay": "2023-08-01",
            "endDay": "2023-09-01",
            "consumption": {
                "energy": 3369.8829,
                "energyM3": 310.0,
                "conversionFactor": 10.871,
                "cost": 267.23171397
            },
            "standingCharge": 25.20400000000002,
            "totalCost": 292.43571397,
            "source": "SMART",
            "nature": "REEL"
        }
    ],
    "yearlyGasEnergies": [
        {
            "year": "2023",
            "beginDay": "2023-06-01",
            "endDay": "2023-09-01",
            "consumption": {
                "energy": 10000.9428,
                "energyM3": 920.0,
                "conversionFactor": 10.871,
                "cost": 793.07476404
            },
            "standingCharge": 75.60787096774197,
            "totalCost": 868.682635007742
        }
    ]
}

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

Data Sources and Calculation

Tracking Period and Time Step

Energy, Cost and Emissions Tracking

Electricity

Examples

Gas

Examples

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

​Data Sources and Calculation

​Tracking Period and Time Step

​Energy, Cost and Emissions Tracking

​Electricity

​Examples

​Gas

​Examples

Data Sources and Calculation

Tracking Period and Time Step

Energy, Cost and Emissions Tracking

Electricity

Examples

Gas

Examples