> ## 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. # Smart charging The cost of charging an electric vehicle can account for up to 20% of a household's electricity budget. Optimizing this energy usage is therefore an interesting and effective way for households to reduce their energy footprint and thus their energy bill. Datanumia offers the users having an Electric Vehicle (E.V) from a wide range of brand the possibility to connect their vehicule to their energy app, and intelligently charge it depending on their energy contract. ## Display that a smart charging scenario is up for the user When a compatible electric vehicle is connected to the platform by the end user, Datanumia automatically activates a control scenario called `DREEV_SMART_CHARGING`. This scenario will use the charging needs defined by the user. Based on his needs and his energy contract, Datanumia will make sure to charge the electric vehicle during the right time to ensure a reduction in the user's energy bill. By using the endpoint : `GET /api/v1/sites/{site-id}/control-scenarios`, this new scenario can then be displayed to the user to let them know that the optimization scenario is running. **Description** : This API returns all control scenarios available for a site, including electic vehicle smart charging ones. The API output provides information on each scenario, such as the status (whether they are in use or not), if the scenario is editable, etc. Note that the `DREEV_SMART_CHARGING` scenario is in a readonly mode, meaning the user cannot deactivate the scenario by himself (`readonly`=`True`). **Input** : * Path parameter: The site identifier (`site-id`) * Query parameter (optional): The scenario mode to filter scenarios on their mode `AUTO` or `MANUAL` **Output** : | label | Description | Example | | - | - | - | | `id` | Unique scenario identifier | `DREEV_SMART_CHARGING` | | `mode` | Type of scenario : automatic or manual | `AUTO` | | `usage` | Usage of the devices remotely controled by this scenario | `ELECTRIC_VEHICLE` | | `active` | Scenario status: whether the scenario has been activated by the user or not. In the case of `DREEV_SMART_CHARGING`, the activation is automatically made at the device detection | `True` | | `available` | Scenario availability. This field is used to check whether the user has all the prerequisites needed to be able to execute commands remotely | `True` | | `readonly` | Scenario property displaying whether it is editable or read-only | `True` | | `executionStatus` | Last site executionStatus. | `RUNNING` | **Example** : `GET /api/v1/sites/1dab569e-778b-4c46-9588-34ca3aeae293/control-scenarios` ```json theme={null} { "scenarios": [ { "id": "AWAY", "mode": "MANUAL", "usage": "HEATING", "active": false, "available": true, "executionStatus": "STOPPED", "readOnly": false }, { "id": "DREEV_SMART_CHARGING", "mode": "AUTO", "usage": "ELECTRIC_VEHICLE", "active": true, "available": true, "executionStatus": "STOPPED", "readOnly": true }, { "id": "OPTIM_TEMPO", "mode": "AUTO", "usage": "HEATING", "active": false, "available": true, "executionStatus": "STOPPED", "readOnly": false } ] } ``` ## Visualize smartcharging sessions and control scenarios gains Datanumia provides an API that can be used to retrieve the history of a site charging sessions. The output provides information about each charging transaction alongside the gains associated with the use of a smart charging control scenario. This API output is paginated and, by default, ten charging sessions are displayed per page. **Endpoint** : `GET /api/v2/sites/{site-id}/control-scenarios/executions` **Input** : * Path parameter: A site identifier (`site-id`) * Required query parameters: * `beginTs`: Begin date of the requested period (included) * `endTs`: End date of the requested period (excluded) * Optional query parameter: * `scenarioId`: scenario identifier * `size` : number of retrieved transaction per page. By default, size=10 * `page` : output page to display Note that to be included, a charging session must start after or at `beginTs` and end strictly before `endTs`. The scenarioId field is not a mandatory query parameter. However, in order to retrieve charging transactions only, it must be set to `scenarioId`=`DREEV_SMART_CHARGING`. **Output** : * A list of charging sessions `executions` with information such as transaction duration, cost, start and end times, total energy consumed, energy consumed via smart charging, smart ratio (quantity of energy consumed via smart charging over total), etc. The charging sessions are sorted in reverse chronological order, i.e. the most recent transaction is the first returned by the API * `energyMeter`: energy consumption in kWh * `total` : total amount of energy consumed during the session * `smart` : amount of energy consumed in smart mode during the session * `unoptimized` : amount of energy consumed in unoptimized mode during the session * `smartRatio`: intelligent charging utilization rate * `cost` : object displaying the real charging session cost (`realCost`) and the estimated cost (`fullUnoptimizedEstimatedCost`) the user would have paid if charging session had not been optimized at all. Therefore the `fullUnoptimizedEstimatedCost` is by definition higher than or equal to the `realCost`. * `gain` : the gain of a charging session is the difference between the real charging session cost (`realCost`) and the cost the user would have paid if charging session had not been optimized at all (`fullUnoptimizedEstimatedCost`). The gain value is necessarily positive. `gain`= `fullUnoptimizedEstimatedCost` - `realCost` * A `totalConsumption` object displaying aggregated information over all transactions included in the API output (all pages): energyMeter consumption, cost and gain. * A `page` object with the number of transaction per page, the total number of transactions, the total number of page and the current page. If the `fullUnoptimizedEstimatedCost` is not available, or if the `fullUnoptimizedEstimatedCost` is lower than `realCost`, the gain will be sent to 0. **Example** : `GET /api/v2/sites/:site-id/control-scenarios/executions?beginTs=2025-01-01T00:00:00Z&endTs=2025-03-18T00:00:00Z&page=0&scenarioId=DREEV_SMART_CHARGING` ```json theme={null} { "units": { "energyMeter": "KWH", "cost": "EUR", "gain": "EUR" }, "_embedded": { "executions": [ { "id": "26caee71-0ab1-44b6-9364-17b95caeb173", "scenarioId": "DREEV_SMART_CHARGING", "type": "STOP", "status": "OK", "ts": "2025-03-12T23:25:00Z", "trigger": {}, "devicesExecutions": [ { "id": "1e78c969-419a-4aa1-845d-876a7d05e64d", "deviceId": "1d94f30c-ab9d-49c2-882f-fa1557ccc30a", "status": "OK", "ts": "2025-03-12T23:25:00Z" } ], "consumption": { "period": { "startTime": "2025-03-12T20:05:00Z", "endTime": "2025-03-12T23:25:00Z" }, "energyMeter": { "total": 1, "unoptimized": 0.4, "smart": 0.6, "smartRatio": 0.6000000000 }, "cost": { "realCost": 0.4248357910906298, "fullUnoptimizedEstimatedCost": 0.5511947910906297 } }, "gain": { "total": 0.1263589999999999 } }, { "id": "d9e0234b-c3ac-42e5-a284-741629baf413", "scenarioId": "DREEV_SMART_CHARGING", "type": "STOP", "status": "OK", "ts": "2025-03-11T23:25:00Z", "trigger": {}, "devicesExecutions": [ { "id": "346b3455-4377-4ed1-bf20-f613a5f30e56", "deviceId": "1d94f30c-ab9d-49c2-882f-fa1557ccc30a", "status": "OK", "ts": "2025-03-11T23:25:00Z" } ], "consumption": { "period": { "startTime": "2025-03-11T20:05:00Z", "endTime": "2025-03-11T23:25:00Z" }, "energyMeter": { "total": 1, "unoptimized": 0.4, "smart": 0.6, "smartRatio": 0.6000000000 }, "cost": { "realCost": 0.4248357910906298, "fullUnoptimizedEstimatedCost": 0.5511947910906297 } }, "gain": { "total": 0.1263589999999999 } }, { "id": "819dc68b-20f2-47a0-83c3-bd03d20ec478", "scenarioId": "DREEV_SMART_CHARGING", "type": "STOP", "status": "OK", "ts": "2025-03-10T23:25:00Z", "trigger": {}, "devicesExecutions": [ { "id": "3d312d21-3596-4c63-9629-3ec6661f586a", "deviceId": "1d94f30c-ab9d-49c2-882f-fa1557ccc30a", "status": "OK", "ts": "2025-03-10T23:25:00Z" } ], "consumption": { "period": { "startTime": "2025-03-10T20:05:00Z", "endTime": "2025-03-10T23:25:00Z" }, "energyMeter": { "total": 1, "unoptimized": 0.4, "smart": 0.6, "smartRatio": 0.6000000000 }, "cost": { "realCost": 0.4248357910906298, "fullUnoptimizedEstimatedCost": 0.5511947910906297 } }, "gain": { "total": 0.1263589999999999 } }, { "id": "0a883157-7a78-4b72-a120-2d85d74b8e0c", "scenarioId": "DREEV_SMART_CHARGING", "type": "STOP", "status": "OK", "ts": "2025-03-09T23:25:00Z", "trigger": {}, "devicesExecutions": [ { "id": "1820309c-003b-4643-bf86-0c6c4211fcd8", "deviceId": "1d94f30c-ab9d-49c2-882f-fa1557ccc30a", "status": "OK", "ts": "2025-03-09T23:25:00Z" } ], "consumption": { "period": { "startTime": "2025-03-09T20:05:00Z", "endTime": "2025-03-09T23:25:00Z" }, "energyMeter": { "total": 1, "unoptimized": 0.4, "smart": 0.6, "smartRatio": 0.6000000000 }, "cost": { "realCost": 0.4248357910906298, "fullUnoptimizedEstimatedCost": 0.5511947910906297 } }, "gain": { "total": 0.1263589999999999 } }, { "id": "e5a7533c-3a64-4a2e-b621-30c634a7709b", "scenarioId": "DREEV_SMART_CHARGING", "type": "STOP", "status": "OK", "ts": "2025-03-08T23:25:00Z", "trigger": {}, "devicesExecutions": [ { "id": "56b8ad1b-5fb9-4a49-b7a8-75e611017d06", "deviceId": "1d94f30c-ab9d-49c2-882f-fa1557ccc30a", "status": "OK", "ts": "2025-03-08T23:25:00Z" } ], "consumption": { "period": { "startTime": "2025-03-08T20:05:00Z", "endTime": "2025-03-08T23:25:00Z" }, "energyMeter": { "total": 1, "unoptimized": 0.4, "smart": 0.6, "smartRatio": 0.6000000000 }, "cost": { "realCost": 0.4248357910906298, "fullUnoptimizedEstimatedCost": 0.5511947910906297 } }, "gain": { "total": 0.1263589999999999 } } ] }, "_links": { "self": { "href": "http://indoor-data-api-live.ssg-dev-01.apps.aws-okd-nodehp.cloud.edelia.net/api/v2/sites/a7d21308-7a5b-4161-9c22-42b67714b593/control-scenarios/executions?beginTs=2025-01-01T15:30:00Z&endTs=2025-03-18T11:00:00Z&scenarioId=DREEV_SMART_CHARGING&page=0&size=10" } }, "page": { "size": 10, "totalElements": 5, "totalPages": 1, "number": 0 }, "totalConsumptions": { "energyMeter": { "total": 5, "unoptimized": 2.0, "smart": 3.0, "smartRatio": 0.60 }, "cost": { "realCost": 2.1241789554531490, "fullUnoptimizedEstimatedCost": 2.7559739554531485 }, "gain": { "total": 0.6317949999999995 } } } ```