Targets

Introduction

The Consumption Targets feature allows users to set an annual energy consumption target—expressed in either monetary value (EUR) or energy units (kWh)—for the current calendar year. Users can track their progress, modify their targets, and configure alerts to monitor how their consumption evolves relative to the set objective.

Eligibility and Prerequisites

Before accessing this feature, the following prerequisites must be met:

Smart Meter: The customer must have a smart meter that is actively communicating, with at least monthly indexes.
Sufficient Data: At least one full month of complete consumption data must be available for the current year.
Baseline Value: A reference value (baseline) must be available via the baseline API, determined using either:
- YEARLY_CONSUMPTION: Based on the customer’s complete consumption data from the previous calendar year.
- SIMILAR_HOME: Based on aggregated consumption data from similar households.

If no baseline value is returned, the Consumption Targets feature will not be available.

User Journey Overview

Propose the Feature

Verify eligibility by checking for a communicating meter, complete monthly data, and a valid baseline value.

Set a Consumption Target

Allow users to define their annual target (in EUR or kWh) along with preferred notification settings.

View Targets

Enable users to access their current target results and their targets history if existing.

Modify Targets

Allow users to update certain aspects of an existing target.

Analysis and Alerts

Users will receive alerts if their target is at risk and in case they activated the option during target setup.

Functional Details

Proposing the Feature to Eligible Customers

Meter Verification: Ensure the customer’s site has a communicating Linky meter.
Data Validation: Confirm that at least one complete month of consumption exists by calling: GET /v2/sites/{site-id}/fluids/elec/consumptions
Baseline Check: Retrieve the baseline consumption value using: GET /v1/sites/{site-id}/energy-target/reference

Expected Response Example:

{
  "energy": 12000,
  "cost": 3000,
  "source": "YEARLY_CONSUMPTION"
}

Setting a Consumption Target

Users can set their target consumption for the year and configure notification preferences. API Endpoint: POST /v2/sites/{siteId}/targets Request Payload Example :

{
  "beginDate": "2021-12-31T23:00:00Z",
  "endDate": "2022-12-31T23:00:00Z",
  "type": "ELEC",
  "unit": "EURO",
  "targetValue": 3000,
  "defaultTargetValue": 3100,
  "notificationChannels": [],
  "notificationType": "NONE",
  "name": "My target"
}

Outcome: The system records the target and calculates the theoretical consumption threshold needed to meet the target.

Viewing Consumption Targets

Retrieve a Specific Target:

API Endpoint:GET /v2/sites/{siteId}/targets/{targetId} Response Example:

{
  "targetId": "2FD7EADA83E24121...",
  "beginDate": "2021-12-31T23:00:00Z",
  "endDate": "2022-12-31T23:00:00Z",
  "type": "ELEC",
  "unit": "EURO",
  "targetValue": 3000,
  "targetValueEquivalent": 12000,
  "defaultTargetValue": 3300,
  "defaultTargetValueEquivalent": 13200,
  "isActive": true,
  "notificationType": "NONE",
  "name": "My target"
}

Retrieve All Targets:

API Endpoint:GET /v2/sites/{siteId}/targets Response: Returns an array of target objects with details such as target ID, generation timestamp, period, target values, notification settings, and active status.

Modifying Consumption Targets

Users can update certain attributes of an existing target. Modifiable Fields: targetValue, notificationChannels, and notificationType. API Endpoint: PUT /v2/sites/{siteId}/targets/{targetId} Request Payload Example :

{
  "siteId": "12345",
  "targetId": "existingTargetId",
  "generationTs": "2021-07-21T22:00:00Z",
  "beginDate": "2021-12-31T23:00:00Z",
  "endDate": "2022-12-31T23:00:00Z",
  "type": "ELEC",
  "unit": "EURO",
  "targetValue": 3000,
  "defaultTargetValue": 3100,
  "notificationChannels": [],
  "notificationType": "NONE",
  "name": "My target"
}

On success, the API returns the targetId with an HTTP 204 response.

Analysis of Trajectory and Alert Generation

Predictive Trajectory Calculation

Purpose: To estimate whether the user will meet their consumption target based on current and historical data. Method: The algorithm calculates the expected outcome of user’s consumption, for each oncoming month. The calculation is updated daily during the current year. Once the year is complete, actual consumption data is used for comparison. Outcome: The analysis returns one of several status messages, such as:

Good Progress: ONPERIOD-GOOD_LASTMONTHS-GOOD, ONYEAR-GOOD, etc.
At Risk: ONPERIOD-BAD_LASTMONTHS-NEUTRAL, etc.
Exceeded Target: ONPERIOD-OVERTARGET, ONYEAR-BAD

API Endpoint: GET /v2/sites/{siteId}/targets-analysis Input: Site ID and an array of target IDs. Response: Detailed analysis including estimated versus real consumption values, status messages, and percentage differences.

Alert Generation

Alerts are generated via a daily batch process based on the analysis results.

Notification Option	Description
`THRESHOLD_OVERRUN`	Alerts the user only if consumption is likely to exceed the annual target
`ON_DIST_INDEX_RECEPTION`	Provides monthly updates on target status
`NONE`	No alerts are sent

Notification Channels	Description
`EMAIL`	user receives an email with his target follow-up
`SMS`	user receives an SMS with his target follow-up
`NONE`	user is not notified if he didn’t subscribe to alerts during target setup

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

Introduction

Eligibility and Prerequisites

User Journey Overview

Functional Details

Proposing the Feature to Eligible Customers

Setting a Consumption Target

Viewing Consumption Targets

Retrieve a Specific Target:

Retrieve All Targets:

Modifying Consumption Targets

Analysis of Trajectory and Alert Generation

Predictive Trajectory Calculation

Alert Generation

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

​Introduction

​Eligibility and Prerequisites

​User Journey Overview

​Functional Details

​Proposing the Feature to Eligible Customers

​Setting a Consumption Target

​Viewing Consumption Targets

​Retrieve a Specific Target:

​Retrieve All Targets:

​Modifying Consumption Targets

​Analysis of Trajectory and Alert Generation

​Predictive Trajectory Calculation

​Alert Generation

Introduction

Eligibility and Prerequisites

User Journey Overview

Functional Details

Proposing the Feature to Eligible Customers

Setting a Consumption Target

Viewing Consumption Targets

Retrieve a Specific Target:

Retrieve All Targets:

Modifying Consumption Targets

Analysis of Trajectory and Alert Generation

Predictive Trajectory Calculation

Alert Generation