> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

```json theme={null}
{
    "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`

```json theme={null}
{
    "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
        }
    ]
}
```