Consumption comparisons

Understanding one’s consumption, or knowing whether one is consuming too much or not can be helpful to improve energy consumption. A good way to address this issue is to use a comparison tool to answer questions such as “How much did I consume last year at the same period ?”, “Can the abnormal temperatures this year explain the rise in my energy bill?, “My bill seems high this year, do other people have the same issue ?” For example, a user could want to compare his electricity or gas consumption (in kWh or €), between one month and the same month the previous year. He could also want to see if the change in energy consumption is correlated with a change in weather temperatures. Another kind of comparison possible is to be able to compare consumption to other similar households. Datanumia’s consumption comparison APIs provide those two types of comparisons giving detailed insights into the energy consumption of a site:

I. Self Comparison
II. Similar Homes Comparison

I. Self comparison APIs

Self comparison APIs allow the user to compare his own consumption at different time intervals over a given period. This service also includes a weather module and a tariff study to help the user explain changes in electrical consumption or budget. Thanks to this weather module, the user knows if the change in weather temperature can explain the change in energy consumption he observed. See below an example of the integration of this API. Self comparison APIs are separated between fluid types :

I.1. Elec
I.2. Gas

Fig 1: Example of self-comparison API integration

I.1. Electrical self comparison API: monthly & yearly comparison

The endpoint GET /api/v1 /sites/{site-id}/consumptions-self-comparison provides the difference in electrical consumptions and costs between two periods (selectedPeriod vs. referencePeriod) API link. (Parameters, Body request, responses, errors and examples are described in it.) Self-Comparison API allows you to implement features that provide your end-user the possibility to compare their electricity consumption between two distinct time periods at this moment. This API can handle different comparison steps according to the user’s requirements (daily, weekly, monthly or customized period). This API takes 6 parameters among which one is optional. To run the self comparison, you need to

Choose a period to analyze (selectedPeriod) and a reference period (referencePeriod) to compare to.
Fill in the fluid type =ELEC
Choose the comparison strategy (SHORTEST_PERIOD_LENGTH or SAME_DAYS_MONTH)

SHORTEST_PERIOD_LENGTH : The longest period is truncated to reach the size of the shortest one. Example : The selected period is 20 successive complete consumptions. The reference period is 27 successive complete consumptions. Reference period is truncated to 20 days. SAME_DAYS_MONTH : Similar periods from two differents years are compared with same month and same days. Example : Compare 1st-15th January 2024 to 1st-15th January 2023.

Example

For example, if you run this API

GET/api/v1/sites/qdsfgxhjcklregdfv/consumptions-self-comparison?fluid=ELEC&strategy=SHORTEST_PERIOD_LENGTH&selectedPeriodBeginTs=2023-01-06'T'00:00:00&selectedPeriodEndTs=2023-01-16'T'00:00:00&referencePeriodBeginTs=2022-01-16'T'00:00:00&referencePeriodEndTs=2021-01-16'T'00:00:00' \

You’ll get the result below. The most important block is “differenceRate” that will give you the currency difference rate and energy difference rate between selected period and reference period in percent:

{
    "units": {
        "cost": "EUR",
        "energyMeter": "KWH"
    },
    "comparisons": [
        {
            "selectedPeriod": {
                "period": {
                    "startTime": "2022-01-06T00:00:00+01:00",
                    "endTime": "2022-01-16T00:00:00+01:00"
                },
                "cost": {
                    "total": 107.8325134
                },
                "energyMeter": {
                    "total": 668.373
                },
                "errorFlags": []
            },
            "referencePeriod": {
                "period": {
                    "startTime": "2023-01-06T00:00:00+01:00",
                    "endTime": "2023-01-16T00:00:00+01:00"
                },
                "cost": {
                    "total": 109.1795602
                },
                "energyMeter": {
                    "total": 677.019
                },
                "errorFlags": []
            },
            "differenceRate": {
                "cost": {
                    "total": -1.2770690335130859
                },
                "energyMeter": {
                    "total": -1.2337902786312938
                }
            }
        }
    ]
}

I.2. Gas self comparison

Gas self comparison APIs are separated into 2 different APIs : a yearly and a monthly comparison one

I.2.1. Gas yearly comparison

The endpoint GET /api/v1 /sites/{site-id}/yearly-gas-energies-comparisons provides the difference in gas consumptions and costs between two years (selectedPeriod vs. referencePeriod) API link. To run the yearly gas comparisons, 2 parameters are required : the site identifier (site-id) and the list of years to be compared (years) Note that to be able to run a comparison for a given site, the latter needs to have complete consumption during selected period, i.e. a cosumption which measurement has been validated and received. Besides, the list of years can take more than two years. The first year of the list will be the comparison year. For example with the list : (2022,2023,2024), the comparison is done between 2023 and 2022 and between 2024 and 2022

Example

For example, if you run the query : GET /api/v1 /sites/330b402e-68f0-48dd-b065-5353063f3017/yearly-gas-energies-comparisons?years=2023,2024 You’ll obtain the result below. The most important block is energyDifferenceRate that will give you the currency difference rate and energy difference rate

[
    {
        "currentYear": {
            "year": "2023",
            "beginMonth": "2023-01",
            "endMonth": "2023-12",
            "fromDate": "2023-01-01",
            "toDate": "2023-12-31",
            "consumption": {
                "energy": 40390,
                "cost": 2240
            },
            "standingCharge": 298,
            "totalCost": 2538
        },
        "previousYear": {
            "year": "2022",
            "beginMonth": "2022-01",
            "endMonth": "2022-12",
            "fromDate": "2022-01-01",
            "toDate": "2022-12-31",
            "consumption": {
                "energy": 40390,
                "cost": 2246
            },
            "standingCharge": 276,
            "totalCost": 2522
        },
        "energyDifferenceRate": 0
    },
    {
        "currentYear": {
            "year": "2024",
            "beginMonth": "2024-01",
            "endMonth": "2024-08",
            "fromDate": "2024-01-01",
            "toDate": "2024-08-10",
            "consumption": {
                "energy": 24490,
                "cost": 1592
            },
            "standingCharge": 180,
            "totalCost": 1772
        },
        "previousYear": {
            "year": "2023",
            "beginMonth": "2023-01",
            "endMonth": "2023-08",
            "fromDate": "2023-01-01",
            "toDate": "2023-08-10",
            "consumption": {
                "energy": 24350,
                "cost": 1351
            },
            "standingCharge": 183,
            "totalCost": 1534
        },
        "energyDifferenceRate": 1
    }
]

I.2.2. Gas monthly comparison

The endpoint GET /api/v1 /sites/{site-id}/monthly-comparisons provides the difference in gas consumptions and costs between a month and this same month the previous year (selectedPeriod vs. referencePeriod) API link. To run the yearly gas comparisons, 3 parameters are required : the site identifier (site-id), the fluid type and the year to be compared (year)

Information	Description	Required
`site-id`	Unique site identifier.	Yes
`fluid`	Represents the energy compared. ELEC or GAS could be selected.	Yes
`year`	Selected year from which we retrieve all months compared. Each month will be compared to Month-1	Yes

Note that to be able to run a comparison for a given site, the latter needs to have complete consumption during selected period, i.e. a cosumption which measurement has been validated and received.

Example

For example, if you run the query GET /api/v1/sites/330b402e-68f0-48dd-b065-5353063f3017/monthly-comparisons?year=2024&fluid=GAS You’ll obtain the result below. The most important block is energyDifferenceRate that will give you the cost difference rate and energy difference rate

[
    {
        "month": 1,
        "currentYearMonthConsumption": {
            "energy": 4340,
            "totalCost": 306
        },
        "previousYearMonthConsumption": {
            "energy": 4340,
            "totalCost": 266
        },
        "beginMonthDay": "--01-01",
        "endMonthDay": "--02-01",
        "isFullMonth": true,
        "energyDifferenceRate": 0,
        "totalCostDifferenceRate": 15
    },
    {
        "month": 2,
        "currentYearMonthConsumption": {
            "energy": 4060,
            "totalCost": 289
        },
        "previousYearMonthConsumption": {
            "energy": 3920,
            "totalCost": 243
        },
        "beginMonthDay": "--02-01",
        "endMonthDay": "--03-01",
        "isFullMonth": true,
        "energyDifferenceRate": 4,
        "totalCostDifferenceRate": 19
    },
    {
        "month": 3,
        "currentYearMonthConsumption": {
            "energy": 3710,
            "totalCost": 266
        },
        "previousYearMonthConsumption": {
            "energy": 3710,
            "totalCost": 231
        },
        "beginMonthDay": "--03-01",
        "endMonthDay": "--04-01",
        "isFullMonth": true,
        "energyDifferenceRate": 0,
        "totalCostDifferenceRate": 15
    },
    {
        "month": 4,
        "currentYearMonthConsumption": {
            "energy": 3300,
            "totalCost": 239
        },
        "previousYearMonthConsumption": {
            "energy": 3300,
            "totalCost": 208
        },
        "beginMonthDay": "--04-01",
        "endMonthDay": "--05-01",
        "isFullMonth": true,
        "energyDifferenceRate": 0,
        "totalCostDifferenceRate": 15
    },
    {
        "month": 5,
        "currentYearMonthConsumption": {
            "energy": 3100,
            "totalCost": 226
        },
        "previousYearMonthConsumption": {
            "energy": 3100,
            "totalCost": 197
        },
        "beginMonthDay": "--05-01",
        "endMonthDay": "--06-01",
        "isFullMonth": true,
        "energyDifferenceRate": 0,
        "totalCostDifferenceRate": 15
    },
    {
        "month": 6,
        "currentYearMonthConsumption": {
            "energy": 2700,
            "totalCost": 200
        },
        "previousYearMonthConsumption": {
            "energy": 2700,
            "totalCost": 175
        },
        "beginMonthDay": "--06-01",
        "endMonthDay": "--07-01",
        "isFullMonth": true,
        "energyDifferenceRate": 0,
        "totalCostDifferenceRate": 14
    },
    {
        "month": 7,
        "currentYearMonthConsumption": {
            "energy": 2480,
            "totalCost": 186
        },
        "previousYearMonthConsumption": {
            "energy": 2480,
            "totalCost": 162
        },
        "beginMonthDay": "--07-01",
        "endMonthDay": "--08-01",
        "isFullMonth": true,
        "energyDifferenceRate": 0,
        "totalCostDifferenceRate": 15
    },
    {
        "month": 8,
        "currentYearMonthConsumption": {
            "energy": 800,
            "totalCost": 60
        },
        "previousYearMonthConsumption": {
            "energy": 800,
            "totalCost": 52
        },
        "beginMonthDay": "--08-01",
        "endMonthDay": "--08-11",
        "isFullMonth": false,
        "energyDifferenceRate": 0,
        "totalCostDifferenceRate": 15
    },
    {
        "month": 9,
        "previousYearMonthConsumption": {
            "energy": 3000,
            "totalCost": 191
        },
        "isFullMonth": true
    },
    {
        "month": 10,
        "previousYearMonthConsumption": {
            "energy": 3420,
            "totalCost": 214
        },
        "isFullMonth": true
    },
    {
        "month": 11,
        "previousYearMonthConsumption": {
            "energy": 3600,
            "totalCost": 224
        },
        "isFullMonth": true
    },
    {
        "month": 12,
        "previousYearMonthConsumption": {
            "energy": 4340,
            "totalCost": 265
        },
        "isFullMonth": true
    }
]

II. Similar home comparison APIs

Similar home comparison APIs allow you to implement features that provide your end-user the possibility to compare their electricity consumption to similar homes. This is made possible by choosing a list of criteria that define what similar homes are. Those criteria are configurable and pre-configured during onboarding installation and are based on user profile (e.g. department, sanitory hot water type, contract, etc.). See below an example of the integration of this API:

similar-home-comparison-example.png.png — Fig 2: Example of similar-home comparison API integration

4 APIs are available depending on the fluid nature (Elec or gas) and the time scale to study (monthly or yearly):

Yearly Elec comparison : API to compare electrical consumption for a selected year with similar homes
Yearly Gas comparison : API to compare gas consumption for a selected year with similar homes
Monthly Elec comparison : API to compare electrical consumption for a selected month with similar homes
Monthly Gas comparison : API to compare gas consumption for a selected month with similar homes

II.1. Yearly comparison

The two yearly endpoints are :

GET /api/v2/sites/{siteId}/similar-home-yearly-gas-comparisons
GET /api/v2/sites/{siteId}/similar-home-yearly-elec-comparisons

To run the yearly comparisons, 2 parameters are required : the site identifier (site-id) and the Year of the beginning of the comparison (begin-year) Note that to be able to run a comparison for a given site, the latter needs to have complete consumption during selected year, i.e. a cosumption which measurement has been validated and received.

Example

For example, if you run the query GET /api/v2/sites/330b402e-68f0-48dd-b065-5353063f3017/similar-home-yearly-elec-comparisons?begin-year=2021 You’ll obtain the result below, which contains useful information like the “percentComparison” object that will give you average diffence between client consumption and similar homes in percent. Moreover, the object “comparisonCriteria” displays all criteria used for the comparison :

[
  {
    "year": 2021,
    "beginMonth": "2021-01",
    "endMonth": "2021-08",
    "energies": {
      "property1": {
        "site": 984,
        "similarHomes": {
          "SH_AVERAGE_CONSUMING": 1236
        }
      },
      "property2": {
        "site": 984,
        "similarHomes": {
          "SH_AVERAGE_CONSUMING": 1236
        }
      }
    },
    "costs": {
      "property1": {
        "site": 984,
        "similarHomes": {
          "SH_AVERAGE_CONSUMING": 1236
        }
      },
      "property2": {
        "site": 984,
        "similarHomes": {
          "SH_AVERAGE_CONSUMING": 1236
        }
      }
    },
    "percentComparison": {
      "SH_AVERAGE_CONSUMING": -20
    },
    "fromDate": "2021-01-01",
    "toDate": "2021-08-05",
    "comparisonCriteria": {
      "DEPARTMENT": "93",
      "OFFER_TYPE": "TRV",
      "SANITORY_HOT_WATER_TYPE": "ELECTRICITE",
      "CLIMATE_ZONE": "H1",
      "RESIDENCE_TYPE": "Pas_Secondaire",
      "SUBSCRIBED_POWER": "9",
      "PRINCIPAL_HEATING_SYSTEM_TYPE": "ELECTRICITE",
      "CLIMATE_SUBZONE": "H1a",
      "TARIFF": "BLEU",
      "HOUSING_TYPE": "MAISON",
      "OPTION": "HPHC"
    }
  }
]

II.2. Monthly comparison

The two monthly endpoints are :

GET /api/v2/sites/{siteId}/similar-home-monthly-gas-comparisons
GET /api/v2/sites/{siteId}/similar-home-monthly-elec-comparisons

To run the monthly comparisons, 3 parameters are required : the site identifier (site-id), the begin month (inculded) and end month (excluded) for the comparison data period(begin-month, end-month) Note that to be able to run a comparison for a given site, the latter needs to have complete consumption during selected period, i.e. a cosumption which measurement has been validated and received The API will respond with all months between the begin month and end month. Watch out, the begin mointh is included whereas the end month is excluded. So for exemple if we set end-month=April, the selected period will end on March 31st.

Example

If you run :

GET /api/v2/sites/330b402e-68f0-48dd-b065-5353063f3017/similar-home-monthly-gas-comparisons?begin-month=2023-01&end-month=2023-06

You’ll obtain the result below which includes useful information like percentComparison object that will give you average diffence between client consumption and similar homes in percent.

[
  {
    "month": "2021-01",
    "fromDate": "2021-01-01",
    "toDate": "2021-02-01",
    "energies": {
      "property1": {
        "site": 984,
        "similarHomes": {
          "SH_AVERAGE_CONSUMING": 1236
        }
      },
      "property2": {
        "site": 984,
        "similarHomes": {
          "SH_AVERAGE_CONSUMING": 1236
        }
      }
    },
    "costs": {
      "property1": {
        "site": 984,
        "similarHomes": {
          "SH_AVERAGE_CONSUMING": 1236
        }
      },
      "property2": {
        "site": 984,
        "similarHomes": {
          "SH_AVERAGE_CONSUMING": 1236
        }
      }
    },
    "percentComparison": {
      "SH_AVERAGE_CONSUMING": -56
    }
  }

]

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

I. Self comparison APIs

I.1. Electrical self comparison API: monthly & yearly comparison

Example

I.2. Gas self comparison

I.2.1. Gas yearly comparison

Example

I.2.2. Gas monthly comparison

Example

II. Similar home comparison APIs

II.1. Yearly comparison

Example

II.2. Monthly comparison

Example

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

​I. Self comparison APIs

​I.1. Electrical self comparison API: monthly & yearly comparison

​Example

​I.2. Gas self comparison

​I.2.1. Gas yearly comparison

​Example

​I.2.2. Gas monthly comparison

​Example

​II. Similar home comparison APIs

​II.1. Yearly comparison

​Example

​II.2. Monthly comparison

​Example

I. Self comparison APIs

I.1. Electrical self comparison API: monthly & yearly comparison

Example

I.2. Gas self comparison

I.2.1. Gas yearly comparison

Example

I.2.2. Gas monthly comparison

Example

II. Similar home comparison APIs

II.1. Yearly comparison

Example

II.2. Monthly comparison

Example