Witty-Home Api Documentation

I. Introduction: Witty charging station overview

A. General description

Figure 1: General schema of the Witty system
Figure 1: General schema of the Witty-Home system.

In one way, if it is connected to the internet, Witty Home charging station sends usage data (such as energy consumption during charging session or station current state) and TIC data (house consumption), only if the end-user gave his consent as explained in the Authorize-TIC section. These data can be accessed through Charging station and Grid meter Witty-Home APIs routes.

In the other way, the charging station can receive a set of commands triggered by the user by calling operators in the Witty-Home APIs routes. For example the end-user can start or stop a charging session.

B. Notifications

The Witty-Home system sends notifications when events (a cable is plugged or unplugged for example) or errors (such as too many load shedding during a charging station) occur on the charging station. The subscription / unsubscription processes and available notifications types are detailed in the Notification section.

II. Subscribing to Witty-Home API through Developer portal

A. Sign up

The developer portal is a website provided by Hager for our partners, they can create an account that allow them to access to the API documentation and test them from the portal.

Fig 2: Dev portal account creation
Figure 2: Create an account in Hager Developer portal.

As soon as the account is created, one received a confirmation mail.

B. Get the Energy Management Starter Pack

The partner can access the list of products by clicking on the “Products” link in the menu bar.

Fig 3: Subscription offers list
Figure 3: Get the list of Hager APIs one can subscribe.

To start with Witty Home API, select the Energy Management Starter Pack.

A subscription associated to the account is then created. The so-created subscription can be renamed.

The user will be notified by email as soon as the subscription request to the product is approved by the administrator.

C. Retrieve an API key

Once the subscription is accepted one can access the Witty Home API.
The API key can now be recovered from the profile, by clicking on the username in the top right corner.

III. Witty Home API at a glance

A. Specifications

B. Usage

We will describe here how to use Witty-Home system main functionalities.

1. Prerequisites

To be able to use any Witty-Home system functionality you need:

2. Installation creation

The first step is to create an installation dedicated to your Witty-Home system if you don’t already have one. An installation is the central point to manage your system devices. A user can see all his installations by calling the Get all user installations route.

To create a Witty-Home installation call the Installation creation route. Once the installation created, you will need to associate the charging station to this installation.

3. On-boarding and first settings

The next step after the installation creation is the association of the charging station to the installation. To do that you will need the unique id (uid) of your device or the value embedded in the QR code, both are available on the charging station packaging. With one of these two information call the device association route.

Once the charging station associated, you should define your TIC consent to authorize or not TIC data transmission. This can be done by calling the Authorize-TIC route. TIC data are your house consumption. (more detail in the Grid meter section).

Then if you gave your consent for TIC data transmission, you should define your electrical tariffs in order to have more realistic comsuption costs statistics. Witty-Home system automatically detects your subscription type to only ask you the corresponding prices. If you did not give your consent, default tariffs will be applied for consumption costs calculation (more details in the Tariffs management section).

4. Charging station functionalities

a. How to set the charge mode of the charging station

To optimize the charging costs, Witty-Home offers 3 differents charging mode :

To set the charge mode of your charging station call the Set charge mode route. This route is asynchronous and will return a 202 Accepted response to indicate that the command was sent to the charging station and will be processed by the device.

Remark: All sockets of the charging station must be available (unplugged) to change the charge mode. You can’t modify it if a car is plugged.

b. How to start a charging session when not in immediate mode

If you are not in immediate charge mode, and plugged a car into the charging station, you can request the device to start a charging session. To do that call the Start session route. This route is asynchronous and will return a 202 Accepted response to indicate that the command was sent to the charging station and will be processed by the device.

c. How to stop a charging session when not in immediate mode

If you are not in immediate charge mode and a car is plugged into the charging station, you can request the station to stop charging the car. To do so call the Stop session route. This route is asynchronous and will return a 202 Accepted response to indicate that the command was sent to the charging station and will be processed by the device.

IV. Interacting with Witty-Home API

In this section we will describe all the APIs routes and their usage. Witty-Home APIs expose 3 types of ressources:

A. Installation

1. Installation description

An installation is the central point of each Hager product type on which you associate your devices. For exemple, on a Witty-Home installation you can add only a Witty charging station whereas on an EOne (Alarm product) installation you can add several security devices as motion or smoke detectors and a security controller. In Witty-Home APIs, an installation is represented by the model shown below in an example:

{
  "installationId": 33,
  "externalId": "XEVFR-myBoxSerialNumber",
  "applicationCode": "flowEvcs",
  "name": "Mon installation Witty-Home",
  "locationName": "Bordeaux",
  "locationGpsCoordinates": {
    "latitude": 44.8,
    "longitude": -0.6
  }
}

Let’s explain each field:

You can get the list of your user account installations by calling this route:
GET /installations

It returns an array of the user account Witty installations

2. Creation

Witty-Home APIs permits you to create your own installation for a Witty-Home product by calling the following route:
POST /installations

This route takes as payload some mandatory installation data as follow:

{
  "name": "Mon installation Witty-Home",
  "locationName": "Bordeaux",
  "locationGpsCoordinates": {
    "latitude": 44.8,
    "longitude": -0.6
  }
}

It returns a 201 Created response with the new installation data.

3. Notifications management

As explained in the overview introduction, Witty-Home system offers the possibility to receive notifications when events or errors occur on your charging station. These notifications can be sent through a webhook to an endpoint in your own information system.

a. How to list notifications subscriptions

To get the list of existing notifications subscriptions on your installation call the following route: GET /installations/{installationId}/event-subscriptions

where {installationId} is the installation identifier.

This route returns an array of event subscriptions and permits you to retreive their identifier to be able to call individual routes. An event subscription is defined by the following model:

{
  "eventSubscriptionId": "bca8d470-ac0b-666b-b986-fb38344db84a",
  "installationId": 33,
  "userId": "123456e6-1234-4c80-ad73-7c445d23f500",
  "protocolCode": "webhook",
  "protocolData": "https://mywebhookendpointurl",
  "filter": {
    "subjectBeginsWith": "",
    "subjectEndsWith": ""
  },
  "state": "Created",
  "creationDate": "2020-11-06T15:31:30Z",
  "modificationDate": "0001-01-01T00:00:00Z"
}

where

To get a single event subscription, you can call this route:
GET /installations/{installationId}/event-subscriptions/{eventSubscriptionId}

where {eventSubscriptionId} is the event subscription identifier.

b. How to subscribe to notifications

To subscribe and receive notifications on a webhook, call the following route:
POST /installations/{installationId}/event-subscriptions

where {installationId} is the installation identifier.

This route requires the following payload:

{
  "protocolCode": "Webhook",
  "protocolData": "https://mywebhookendpointurl",
  "eventType": "string",
}

c. How to unsubscribe to notifications

To unsubscribe to notifications, two routes are available.

To delete all your account subscriptions in one call:
DELETE /installations/{installationId}/event-subscriptions

where {installationId} is the installation identifier.

To delete a specific subscription with its identifier:
DELETE /installations/{installationId}/event-subscriptions/{eventSubscriptionId}

where {installationId} is the installation identifier and {eventSubscriptionId} the identifier of the subscription to delete. To get the subscription identifier call the Get subscriptions route.

4. Sharing your installation with your installer

Witty-Home system allows you to share your installation with your installer to permit him to monitor your charging station. He will only see general data and will not be able to call commands such as starting or stopping charges neither see your charging station and grid meter costs or consumptions.

a. Send an invitation to your installer

To share your installation you must send an email invitation to your installer by calling this route:

POST /installations/{installationId}/invitations

where {installationId} is the installation identifier.

This route requires the following payload:

{
  "email": "myinstaller@example.com",
  "cultureCode": "fr-FR"
}

It returns a 201 Created response with the new invitation data.

b. Get the status of your invitation

To check the status of your pending invitation call:

GET /installations/{installationId}/invitations

where {installationId} is the installation identifier.

This will return an invitationStatus formatted as follow:

{
  "email": "myinstaller@example.com",
  "installationName": "my Home charging station",
  "installationId": 33,
  "expirationDate": "2022-10-17T15:56:00Z"
}

c. Delete an invitation

If you want to cancel a pending invitation, you can delete it with this route:

DELETE /installations/{installationId}/invitations/{email}

where

It returns a 204 NoContent response when deletion is done.

d. As an installer, accept an invitation

To accept an invitation, an installer can call this route:

POST /invitations/operators/accept/{activationCode}

where {activationCode} is the activation code received in the invitation email.

It returns a 200 OK response when the invitation is successfully accepted.

/!\This route only works with an installer account !

e. Get your installation users

To get a list of all users existing on your installation, use this route:

GET /installations/{installationId}/users

where {installationId} is the installation identifier.

The return will be an array of UserModel matching the following model:

[
  {
    "accountId": "string",
    "accountFirstName": "string",
    "accountLastName": "string",
    "accountEmail": "string",
    "authorizationGroups": [
      "ownerActive"
    ],
    "roleCode": "owner",
    "enabled": true
  }
]

f. Disable the installer

If you want to temporarily stop sharing your installation with your installer you can disable him. He will not be able to access your data until you enable him again.

POST /installations/{installationId}/users/{accountId}/operators/disable

where

It returns a 204 NoContent response when the installer is disable.

g. Enable the installer

When you disabled your installer and want to allow him to monitor your installation again call this route to enable him:

POST /installations/{installationId}/users/{accountId}/operators/enable

where

It returns a 204 NoContent response when the installer is enabled.

h. Delete the installer

To definitively stop sharing your installation with an installer, you can remove it from your installation with this route:

DELETE /installations/{installationId}/users/{accountId}

where

It returns a 204 NoContent response when the installer is deleted.

B. Charging station

Main functionalities of Witty-Home system permit you to check your charging station current state and configuration, interact with it through some asynchronous commands to optimize your charging sessions and retrieve statistics about your electric consumption as well of your charging session or your whole house (if you gave your consent for TIC data transmission).

1. Charging station description

In Witty-Home APIs, the charging station is described by the following model:

{
  "id": "60e0d33e-cd45-4382-9e4d-c64002c3f5a7",
  "serialNumber": "1234ABCDEF5678",
  "uuid": "SyybhpX7Lzo3uhTzCoWQbn",
  "installationParentId": 33,
  "type": "chargingStation",
  "properties": {
    "installationDate": "2020-04-15T13:28:13Z",
    "productionDate": "2020-04-07T13:27:25Z",
    "productReference": "XEVFR",
    "macAddress": "F8-F5-05-DC-33-83",
    "wifiSsid": "myInternetBox-ABCD",
    "friendlyName": "my garage charging station",
    "phaseNumber": "threePhase",
    "erlConnected": true,
    "ticConnected": "connected",
    "nightModeConnected": "dn",
    "sheddingMode": "chpLoadShedding7A13A",
    "averageEvConsumption": "14.2",
    "isDefaultAverageEvConsumption": false,
    "tariff1": "hc",
    "tariff2": "hp",
    "tariff3": "hc",
    "tariff4": "hc",
    "tariff5": "hp",
    "tariff6": "hc",
    "tariff7": "hp",
    "tariff8": "hc",
    "tariff9": "hp",
    "tariff10": "hc",
    "authorizeTic": "consent",
    "availability": "occupied",
    "chargeMode": "immediate",
    "carPlugStatus": "m3",
    "keySwitch": "locked",
    "timezone": "Romance Standard Time",
    "culture": "fr-fr",
    "connectivityType": "ethernet",
    "evcsLocked": true,
    "error": {
      "code": 0
    },
    "currentSession": {
      "startDate": "2020-11-09T10:50:11Z",
      "duration": "03:33",
      "totalSessionEnergy": 99.0,
      "totalSessionCost": 0.915,
      "chargingSpeed": "optimal",
      "chargingDuration": "03:15",
      "rangeRecoveredByEV": 697
    },
    "lastSession": {
      "startDate": "2020-09-03T13:59:50Z",
      "endDate": "2020-09-03T14:01:16Z",
      "sessionDuration": "00:30",
      "chargingDuration": "00:15",
      "totalSessionEnergy": 38,
      "totalSessionCost": 0.422,
      "rangeRecoveredByEV": 267
    },
    "heartbeat": {
      "heartbeat": true,
      "receptionDate": "2020-11-09T10:50:11Z"
    }
  }
}

Let’s explain each charging station field:

2. Charging station operations

Witty-Home APIs exposes synchronous routes to get, add and remove a charging station from an installation and asynchronous routes to send commands to your device.

a. Get all charging stations of an installation

To get the list of charging station available on an installation (usually one), call the route:
GET /installations/{installationId}/charging-stations

where {installationId} is the installation identifier.

This route returns an array of charging stations and permits you to retreive their identifier to be able to call individual routes.

b. Get a charging station by its identifier

You can get the detail of a specific charging station with its identifier by calling this route:
GET /installations/{installationId}/charging-stations/{chargingStationId}

where

This route returns the detail of a specific charging station.

c. Add a charging station on an installation

To associate a charging station to your installation call the following route:
POST /installations/{installationId}/charging-stations

where {installationId} is the installation identifier.

This route requires the following payload:

{
  "uid": "Fbo5WTTsSeeLQ8YYoLzNwN",
  "qrCode": "https://hgr.io/u/Fbo5WTTsSeeLQ8YYoLzNwN",
  "timezone": "Romance Standard Time",
  "country": "fr-fr"
}

You must pass at leat one of the two parameters uid or qrCode. The uid and QR code can be found on the charging station packaging.
The timezone must be one of [GMT Standard Time | Romance Standard Time | W. Europe Standard Time].
The country must be one of [en-gb | fr-fr | de-de].

The route returns a 201 Created response with the newly added charging station information as response value.

d. Remove a charging station from an installation

To remove a charging station from your installation call the following route:
DELETE /installations/{installationId}/charging-stations/{chargingStationId}

where

It returns a 204 No Content response when the dissociation is successful.

e. Set charge mode

To modify the charge mode of your station call the following route with the desired mode:
POST /installations/{installationId}/charging-stations/{chargingStationId}/operators/set-charge-mode

where

This route takes the following payload as input:

{
  "chargeMode": "immediate"
}

The charge mode must be one of ["immediate" | "deferred" | "deferredExclusive"]
See How to set the charge mode of the charging station section for explainations of each mode.

f. Start a charging session

To start a charging session if your car is plugged and your station is not in immediate mode (otherwise it will automatically start when you plug the car) call this route:
POST /installations/{installationId}/charging-stations/{chargingStationId}/operators/start

where

This route returns a 202 Accepted response to confirm that the command was sent to the charging station and will be processed by the device.

g. Stop a charging session

To stop a charging session, call the following route:
POST /installations/{installationId}/charging-stations/{chargingStationId}/operators/stop

where

This route returns a 202 Accepted response to confirm that the command was sent to the charging station and will be processed by the device.

h. Update a charging station

You can update few properties of your charging station by calling this route:
PUT /installations/{installationId}/charging-stations/{chargingStationId}

where

This route takes the following payload as input:

{
  "friendlyName": "my borne",
  "ledPower": 30,
  "averageEvConsumption": 37.5,
  "tariff1": "hp",
  "tariff2": "hc",
  "tariff3": "hp",
  "tariff4": "hp",
  "tariff5": "hc",
  "tariff6": "hp",
  "tariff7": "hp",
  "tariff8": "hp",
  "tariff9": "hp",
  "tariff10": "hp"
}

All fields are optional you can only provide the one you need to update.

Remark: All sockets of the charging station must be available (unplugged) to change ledPower or one of the tariffX parameters. You can’t modify them if a car is plugged as it will need your charging station to reboot to apply the update.

This route returns a 202 Accepted response to confirm that the command was sent to the charging station and will be processed by the device.

3. Charging station measures

a. Measures description

A measure is the recording of a metric data on a time basis. A metric is a value on which an aggregation operation (sum, average, count, min-max) can be done. Measures metadata are defined by the following model:

{
  "measureId": "1",
  "name": "EnergyConsumption",
  "type": "Energy",
  "unit": "kWh",
  "periodicity": "10m"
}

b. Get all charging station measures metadata

To get the metadata of all available measures of a charging station, call the route:
GET /installations/{installationId}/charging-stations/{chargingStationId}/measures

where

This route returns an array of charging station measures and permits you to retreive their identifier to be able to call individual routes.

c. Get a charging station measure by its identifier

To get the metadata of a specific measure, call the route:
GET /installations/{installationId}/charging-stations/{chargingStationId}/measures/{measureId}

where

This route returns the metadata of a specific measure.

d. Get charging station measure values aggregated by an operator

You can aggregate measure values by calling the ‘operators’ routes:
POST /installations/{installationId}/charging-stations/{chargingStationId}/measures/{measureId}/operators/sum
POST /installations/{installationId}/charging-stations/{chargingStationId}/measures/{measureId}/operators/count
POST /installations/{installationId}/charging-stations/{chargingStationId}/measures/{measureId}/operators/average
POST /installations/{installationId}/charging-stations/{chargingStationId}/measures/{measureId}/operators/min-max

where

These routes take the aggregation parameters as payload formatted as follow:

{
  "startDate": "2020-06-02T00:58:24.458Z",
  "endDate": "2020-06-04T12:15:33.458Z",
  "step": "day"
}

The result values are grouped by date and tariff type (HC: low tariff or HP: high tariff). Here is an example of the result with a TEMPO subscription for a search over a day with a step hour:

[
  {
    "date": "2020-06-29T00:00:00.000Z",
    "tariffType": "hp",
    "value": 6,
    "valueHpjb": 3,
    "valueHpjw": 2,
    "valueHpjr": 1
  },
  {
    "date": "2020-06-29T08:00:00.000Z",
    "tariffType": "hc",
    "value": 15,
    "valueHcjb": 4,
    "valueHcjw": 5,
    "valueHcjr": 6
  }
]

In the result array, for each couple date and tariffType you will find:

Here is the model with the exhaustive list of properties. You will never get all of them as you will only see the tariff values matching your subscription, its purpose is just to show all existing fields:

[
  {
    "date": "2020-06-29T15:38:45.329Z",
    "value": 0,
    "valueMin": 0,
    "valueMax": 0,
    "tariffType": "hp",
    "valueTh": 0,
    "valueHc": 0,
    "valueHp": 0,
    "valueHn": 0,
    "valuePm": 0,
    "valueHcjb": 0,
    "valueHpjb": 0,
    "valueHcjw": 0,
    "valueHpjw": 0,
    "valueHcjr": 0,
    "valueHpjr": 0,
    "valueTariff1": 0,
    "valueTariff2": 0,
    "valueTariff3": 0,
    "valueTariff4": 0,
    "valueTariff5": 0,
    "valueTariff6": 0,
    "valueTariff7": 0,
    "valueTariff8": 0,
    "valueTariff9": 0,
    "valueTariff10": 0
  }
]

4. Charging station logs

a. Charging station logs description

A log is the recording of a non-metric data on a time basis. A non-metric is a value on which aggregation operations (sum, average, …) cannot be done. Logs are defined by the following metadata:

[
  {
    "logId": "1",
    "name": "SessionStart",
    "periodicity": "Immediate"
  }
]

b. Get all charging station logs metadata

To get the metadata of all available logs for a charging station, call the route:
GET /installations/{installationId}/charging-stations/{chargingStationId}/logs

where

This route returns an array of charging station logs and permits you to retreive their identifier to be able to call individual routes.

c. Get a charging station log by its identifier

To get the metadata of a specific log, call the route:
GET /installations/{installationId}/charging-stations/{chargingStationId}/logs/{logId}

where

This route returns the metadata of a specific log.

d. Get charging station log values aggregated by count

The only operators available on a log are count and list as logs are non-metric data. To count a log values call this route: POST /installations/{installationId}/charging-stations/{chargingStationId}/logs/{logId}/operators/count

where

This route takes the count aggregation parameters as payload formatted as follow:

{
  "startDate": "2020-06-02T00:58:24.458Z",
  "endDate": "2020-06-04T12:15:33.458Z",
  "step": "day"
}

The result values are grouped by date. Here is an example of a count by day of SessionStart log (logId = 1):

[
  {
    "date": "2020-04-16T00:00:00Z",
    "value": 5.0,
    "logName": "SessionStart"
  },
  {
    "date": "2020-04-20T00:00:00Z",
    "value": 4.0,
    "logName": "SessionStart"
  }
]

e. Get charging station log values list

To get the history of a specific log values, call this route: POST /installations/{installationId}/charging-stations/{chargingStationId}/logs/{logId}/operators/list

where

This route takes the search span parameters as payload formatted as follow:

{
  "startDate": "2020-06-02T00:58:24.458Z",
  "endDate": "2020-06-04T12:15:33.458Z"
}

This route returns the full history of the given log for the search span.
Here is an example of a StartSession log search:

[{
  "date": "2020-09-03T13:58:08Z",
  "value": {
    "evcsSocket": "m3",
    "evcsCableValue": 32
  },
  "logName": "SessionStart"
}, {
  "date": "2020-09-03T13:59:50Z",
  "value": {
    "evcsSocket": "m3",
    "evcsCableValue": 32
  },
  "logName": "SessionStart"
}, {
  "date": "2020-11-09T10:50:11Z",
  "value": {
    "evcsSocket": "m3",
    "evcsCableValue": 32
  },
  "logName": "SessionStart"
}]

f. Get charging station logs values list

To get the history of all logs values in one request, call the following route. As there is no filter by log id, there can be a lot of results. We recommand you to narrow the time range of your search.
POST /installations/{installationId}/charging-stations/{chargingStationId}/logs/operators/list

where

This route takes the search span parameters as payload formatted as follow:

{
  "startDate": "2020-06-02T00:58:24.458Z",
  "endDate": "2020-06-04T12:15:33.458Z"
}

The result is an array of all logs values over your search range whatever their type. Here is an example:

[{
  "date": "2020-09-03T13:58:08Z",
  "value": {
    "keySwitch": "unlocked"
  },
  "logName": "KeySwitch"
}, {
  "date": "2020-09-03T13:58:08Z",
  "value": {
    "evcsSocket": "m3",
    "evcsCableValue": 32
  },
  "logName": "SessionStart"
}, {
  "date": "2020-09-03T13:58:08Z",
  "value": {
    "chargeMode": "deferredExclusive"
  },
  "logName": "ChargeMode"
}, {
  "date": "2020-09-03T13:58:08Z",
  "value": {
    "code": "noError",
    "state": false
  },
  "logName": "Errors"
}, {
  "date": "2020-09-03T13:58:08Z",
  "value": {
    "event": 3.0,
    "timestamp": "2020-09-03T13:58:08Z",
    "message": "MyNewSSID"
  },
  "logName": "CyberSecurity"
}, {
  "date": "2020-09-03T13:59:02Z",
  "value": {
    "chargingDuration": 900,
    "sessionDuration": 1800,
    "cost": 0.0035999999999999995,
    "energy": 24.0
  },
  "logName": "SessionEnd"
}]

Details of error codes and cybersecurity events codes are available in the Notifications section.
For charge modes details see How to change charge mode.

C. Grid meter

First of all, let’s describe what is a grid meter in the french context.
The grid meter is the central point of a house electrical installation. It permanently measures and surveys the electrical consumption. It breaks the current if consumption reaches the installation material limits (the maximum current intensity in Ampere it can support) or the provider subscription limits (the maximum intensity subscribed by the contract with the provider : for example a 6 kVA contract allows a maximum consumption of 30 A). The grid meter is also a smart device: it can transmit data to other devices throught a wired connection called the TIC (télé-information client) or for the more recent Linky device by wireless connection with en ERL (Emetteur Radio Linky).
Once you associated your charging station with your installation and if you gave your consent for the TIC transmission (see Authorize-TIC route to know how to set the TIC consent), you will be able to access your house data. We will see more details about these data below.

1. Grid meter description

a. Grid meter fields

This section presents a detailed description of all grid meter properties, essentially coming from TIC data.
In Witty-Home APIs, the grid meter is represented by the model shown below in an example:

{
  "id": "a6536308-fc1d-4930-ae1a-19a526958c75",
  "installationParentId": 42,
  "type": "gridMeter",
  "properties": {
    "generalConsumption": {
      "consumptionTotalIndex": 652,
      "consumptions": [
        {
          "name": "HC",
          "value": 304
        },
        {
          "name": "HP",
          "value": 348
        }
      ]
    },
    "ticType": 5,
    "intensitySubscribed": 60,
    "currentTariff": "HC",
    "gridSubscription": "HCHP"
  }
}

Let’s explain each field:

b. TIC types

In this section we will explain different TIC types values:

To summarize, an Historic TIC is a specific format for EDF (Electricité de France) tariffs and subscriptions whereas Standard TIC is a set of 10 custom tariffs.

c. Subscriptions and tariffs

As we explained in the previous section, there will be 2 types of subscriptions and each subscription has its specific tariffs.

On the one hand, there are EDF subscriptions, which imply that your grid meter runs in Historic TIC mode. Let’s describe each EDF subscription and its associated tariffs:

On the other hand, there are all other subscriptions of alternative providers. For all these providers your grid meter runs in Standard TIC mode. This mode permits alternative providers to set up to 10 tariffs with low or high prices. In this case, Witty system consolidates all alternative contracts to one STANDARD subscription which exposes these 10 customizable tariffs:

2. Grid meter operations

a. Get all grid meters of an installation

To get the list of grid meters available on an installation (usually one), call the route:
GET /installations/{installationId}/grid-meters

where {installationId} is the installation identifier.

This route returns an array of grid meters and permits you to retreive their identifier to be able to call individual routes.

b. Get a grid meter by its identifier

You can get the detail of a specific grid meter with its identifier by calling this route:
GET /installations/{installationId}/grid-meters/{gridMeterId}

where

This route returns the detail of a specific grid meter.

To set your consent and authorize or not the transmission of your TIC data to Hager’s system, call the following route:
POST /installations/{installationId}/grid-meters/{gridMeterId}/operators/authorize-tic

where

This route takes as payload an object with a unique property authorizeTIC. You must set it to:

3. Grid meter measures

a. Description

As for charging station, a measure is the recording of a metric data on a time basis. A metric is a value on which an aggregation operation (sum, average, count, min-max) can be done. Measures metadata are defined by the following model:

{
  "measureId": "1",
  "name": "EnergyConsumption",
  "type": "Energy",
  "unit": "kWh",
  "periodicity": "10m"
}

b. Get all grid meter measures metadata

To get the metadata of all available measures of a grid meter, call the route:
GET /installations/{installationId}/grid-meters/{gridMeterId}/measures

where

This route returns an array of grid meter measures and permits you to retreive their identifier to be able to call individual routes.

c. Get a grid meter measure by its identifier

To get the metadata of a specific measure, call the route:
GET /installations/{installationId}/grid-meters/{gridMeterId}/measures/{measureId}

where

This route returns the metadata of a specific measure.

d. Get grid meter measure values aggregated by an operator

You can aggregate measure values by calling the ‘operators’ routes:
POST /installations/{installationId}/grid-meters/{gridMeterId}/measures/{measureId}/operators/sum
POST /installations/{installationId}/grid-meters/{gridMeterId}/measures/{measureId}/operators/count
POST /installations/{installationId}/grid-meters/{gridMeterId}/measures/{measureId}/operators/average
POST /installations/{installationId}/grid-meters/{gridMeterId}/measures/{measureId}/operators/min-max

where

These routes take the aggregation parameters as payload formatted as follow:

{
  "startDate": "2020-06-02T00:58:24.458Z",
  "endDate": "2020-06-04T12:15:33.458Z",
  "step": "day"
}

The result format is the same as for the charging station measure aggregation route.

4. Grid meter logs

a. Grid meter logs description

A log is the recording of a non-metric data on a time basis. A non-metric is a value on which aggregation operations (sum, average, …) cannot be done. There are two grid meter logs defined by the following metadata:

[
  {
    "logId": "1",
    "name": "CurrentTariff",
    "periodicity": "Immediate"
  },
  {
    "logId": "2",
    "name": "TicType",
    "periodicity": "Immediate"
  }
]

The first log is the recording of the active tariff on the grid meter over time and the second one is the recording of TIC type changes.

b. Get all grid meter logs metadata

To get the metadata of all available logs of a grid meter, call the route:
GET /installations/{installationId}/grid-meters/{gridMeterId}/logs

where

This route returns an array of grid meter logs and permits you to retreive their identifier to be able to call individual routes.

c. Get a grid meter log by its identifier

To get the metadata of a specific log, call the route:
GET /installations/{installationId}/grid-meters/{gridMeterId}/logs/{logId}

where

This route returns the metadata of a specific log.

d. Get log values aggregated by count

The only operators available on a log are count and list as logs are non-metric data. To count a log values call this route: POST /installations/{installationId}/grid-meters/{gridMeterId}/logs/{logId}/operators/count

where

This route takes the count aggregation parameters as payload formatted as follow:

{
  "startDate": "2020-06-02T00:58:24.458Z",
  "endDate": "2020-06-04T12:15:33.458Z",
  "step": "day"
}

The result values are grouped by date. Here is an example of a count by day of TicType log (logId = 2):

[
  {
    "date": "2020-04-16T00:00:00Z",
    "value": 22.0,
    "logName": "TicType"
  },
  {
    "date": "2020-04-20T00:00:00Z",
    "value": 4.0,
    "logName": "TicType"
  }
]

e. Get log values list

To get the history of a specific log values, call this route: POST /installations/{installationId}/grid-meters/{gridMeterId}/logs/{logId}/operators/list

where

This route takes the search span parameters as payload formatted as follow:

{
  "startDate": "2020-06-02T00:58:24.458Z",
  "endDate": "2020-06-04T12:15:33.458Z"
}

This route returns the full history of the given log for the search span.
The CurrentTariff log has this result format:

[
  {
    "date": "2020-04-20T07:38:41Z",
    "value": {
      "currentTariff": "HPJB"
    },
    "logName": "CurrentTariff"
  },
  {
    "date": "2020-04-20T07:29:41Z",
    "value": {
      "currentTariff": "HCJB"
    },
    "logName": "CurrentTariff"
  }
]

The result for TicType logs is:

[
  {
    "date": "2020-04-20T07:38:41Z",
    "value": {
      "ticType": "historicMono"
    },
    "logName": "TicType"
  },
  {
    "date": "2020-04-20T07:29:41Z",
    "value": {
      "ticType": "idle"
    },
    "logName": "TicType"
  }
]

5. Tariffs management

a. Tariffs description

Witty Home system offers you the possibilty to view your house electrical consumptions cost by setting your tariffs prices. If you don’t set your own prices, default values are used to keep this feature available. A tariff is defined by the following model:

{
  "id": "th",
  "installationParentId": 0,
  "friendlyName": "my base tariff",
  "currency": "eur",
  "isDefault": true,
  "values": [
    {
      "beginDate": "2020-07-03T08:27:12.688Z",
      "value": 0.25
    }
  ]
}

b. Get all tariffs

To get the prices historic of all your tariffs call this route:
GET /installations/{installationId}/grid-meters/{gridMeterId}/tariffs

where

This route returns an array of tariff with for each tariff its price historic.

c. Get a tariff by its identifier

To get the prices historic of a single tariff, call this route:
GET /installations/{installationId}/grid-meters/{gridMeterId}/tariffs/{tariffId}

where

This route returns a single tariff with its prices over time.

d. Set tariffs prices

Witty Home system permits you to define your own tariffs prices to have the most accurate consumption cost calculation, not only for your house consumption but mostly for your charging session consumption. If you don’t set custom tariffs, the system uses defaults prices to calculate costs anyway. To set your own tariff call the following route and give all the tariff that are needed for your subscription (cf Subscriptions and tariffs section). For example if you have a HCHP contract you must give a price for the two tariffs HC and HP.
POST /installations/{installationId}/grid-meters/{gridMeterId}/tariffs

where

The tariff payload must be formatted as follow, for example with a BASE subscription you need to send the only tariff TH:

[
  {
    "id": "th",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0.33
  }
]

If you have a HCHP subscription:

[
  {
    "id": "hc",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0.33
  },
  {
    "id": "hp",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0.42
  }
]

For a STANDARD subscription you must pass the 10 custom tariffs even if you want to set the price for 3 of them:

[
  {
    "id": "tariff1",
    "friendlyName": "my low cost tariff",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0.33
  },
  {
    "id": "tariff2",
    "friendlyName": "my high cost tariff",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0.806
  },
  {
    "id": "tariff3",
    "friendlyName": "my special week-end tariff",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0.42
  },
  {
    "id": "tariff4",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0
  },
  {
    "id": "tariff5",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0
  },
  {
    "id": "tariff6",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0
  },
  {
    "id": "tariff7",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0
  },
  {
    "id": "tariff8",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0
  },
  {
    "id": "tariff9",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0
  },
  {
    "id": "tariff10",
    "currency": "eur",
    "beginDate": "2020-07-03T13:25:37.120Z",
    "value": 0
  }
]

The route returns the full historic of all your subscription tariffs prices. If we stay on the example of a BASE subscription:

{
  "id": "th",
  "installationParentId": 0,
  "friendlyName": "my base tariff",
  "currency": "eur",
  "isDefault": false,
  "values": [
    {
      "beginDate": "2020-07-03T13:25:37.120Z",
      "value": 0.33
    },
    {
      "beginDate": "2020-01-02T10:00:00.000Z",
      "value": 0.22
    }
  ]
}