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

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

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

## User Journey Overview

<Steps>
  <Step title="Propose the Feature">
    Verify eligibility by checking for a communicating meter, complete monthly data, and a valid baseline value.
  </Step>

  <Step title="Set a Consumption Target">
    Allow users to define their annual target (in EUR or kWh) along with preferred notification settings.
  </Step>

  <Step title="View Targets">
    Enable users to access their current target results and their targets history if existing.
  </Step>

  <Step title="Modify Targets">
    Allow users to update certain aspects of an existing target.
  </Step>

  <Step title="Analysis and Alerts">
    Users will receive alerts if their target is at risk and in case they activated the option during target setup.
  </Step>
</Steps>

## 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:**

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

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

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

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