Récupérez vos données de compteur intelligent avec Javascript et l’API Switchgrid
Cet article a pour but d’aider les développeurs à récupérer la consommation d’un compteur électrique communiquant grâce à l’API de switchgrid.
Un repository GitHub contient le code nécessaire à cette récupération (voir TL;DR), et cet article propose une aide étape par étape.
TL;DR - Pour aller droit au but
- Créez votre compte sur app.switchgrid.tech/signup
- Renseignez votre PRM et créez un token
- Clonez le répo Switchgrid/blog-article-javascript
npm install
touch .env && touch .env && echo 'API_TOKEN=****************' > .env
- Adaptez
src/createAsk.js
en entrant vos données de contrat. npm run start
et laissez-vous guider pour donner votre consentement et pour obtenir les données
Guide détaillé
1. Créez votre compte Switchgrid (1 min)
- Rendez-vous sur app.switchgrid.tech/signup
- Une fois inscrit.e, créez une clef d’API depuis votre espace Switchgrid
- Renseignez le numéro de point de livraison (aussi appelé PDL / PRM / Point d’acheminement) duquel vous souhaitez récupérer les données.
2. Installez le SDK (5 min)
Installez le SDK de Switchgrid. Vous pouvez utiliser la librairie npm api pour générer les fichiers client à partir de la spécification OpenAPI 3.1 de Switchgrid.
npx api install https://app.switchgrid.tech/openapi-spec/json
Créez un fichier index.js
et initialisez le SDK
const switchgrid = require("@api/switchgrid");
async function program() {
switchgrid.auth("9f8c1c53a4************3680f096"); // Your token
...
}
3. Donnez votre consentement (5 min)
Pour demander à une personne (le signer
) de signer un consentement pour récupérer les données d’un contrat électrique, utilisons l’endpoint pour créer un Ask
(demande de consentement) :
Vous aurez besoin de remplir les champs suivants:
signer
: d’une personne qui signe le consentement (vous-même par exemple)electricityContracts
: des données du contrat électrique (PDL, adresse, nom du titulaire)consentDuration
: la durée de validité de ce consentementconsentCollectionMedium
permet de décrire la façon dont on veut récupérer le consentement, en l’occurence un simple formulaire webscopesAndPurpose
permet de décrire les autorisations que l’on demande ausigner
, en l’occurence de récupérer la courbe de charge en consommation liée à son compteur, pour les 24 derniers mois - ainsi que le but dans lequel on le fait (ici une étude de performance énergétique)
Voilà un exemple à adapter :
const prm = "00000000000000"; // Remplaçer par votre PDL
const {
data: { id: askId, consentCollectionDetails, status },
} = await switchgrid.ask({
electricityContracts: [
{
prm,
address: {
street: "1 rue de la paix",
postalCode: "75001",
city: "Paris",
country: "France",
},
heldBy: {
genre: "M",
firstName: "Prénom",
lastName: "Nom",
email: "prenom.nom@domaine.com",
},
},
],
signer: {
email: "nom.prenom@domaine.com",
genre: "M",
firstName: "Prénom",
lastName: "Nom",
phone: "+33677802571",
},
consentDuration: "1 day",
consentCollectionMedium: {
service: "WEB_HOSTED",
},
scopesAndPurpose: [
{
scopes: [
{
id: "ELECTRICITY_TIMESERIES",
args: {
types: ["LOADCURVE"],
directions: ["CONSUMPTION"],
},
},
],
purposes: ["ENERGY_PERFORMANCE_STUDY"],
},
],
});
Switchgrid va vérifier l’adéquation entre l’adresse, le titulaire (heldBy
) et le PDL de cette demande. Le champ status
de l’objet retourné permet de savoir si c’est bien le cas.
- ❌ Dans le cas où la vérification échoue, le
status
prendra la valeurADDRESS_CHECK_FAILED
. Dans ce cas, merci de vérifier le titluaire et l’adresse du contrat.
if (status === "ADDRESS_CHECK_FAILED") {
console.error(
"L'addresse, le nom du titulaire et le PDL ne correspondent pas"
);
return;
}
- ✅ Dans le cas où la vérification aboutit, le
status
passe àPENDING_USER_ACTION
, et le champconsentCollectionDetails
contient une url à laquelle il faut signer le consentement
if (consentCollectionDetails) {
console.log({ askId, url: consentCollectionDetails.userUrl });
}
On obtient une URL du type https://app.switchgrid.tech/c/ask/1ec8ad49-f3ae-4b76-a7b0-6a5d6b4d1808
.
Vous pouvez alors signer ce consentement en vous rendant à cette URL
askId
.Ask
, vous pouvez utiliser la méthode switchgrid.getAsks()
pour lister les Ask
existants.
4. Récupérez les données (10 min)
Une fois signé, ce consentement, pendant sa période de validité, vous permet de récupérer les données de consommation.
Afin de commander des données pour votre compteur, vous devez récupérer l’id du consentment qui vient d’être donné.
const { status, consentIds } = await switchgrid.getAsk({ askId })
consentIds
contient un objet qui donne les identifiants de consentements pour chaque PDL que vous avez mis dans le Ask
.
Pour effectuer une commande de données, l’appel est le suivant :
await switchgrid.order({
consentId: consentIds[prm],
requests: [
{
type: "LOADCURVE",
direction: "CONSUMPTION",
},
],
});
Il vous renvoie un orderId
. Vous pouvez ensuite consulter l’état de cet Order grâce à getOrder()
:
const { status, requests } = await switchgrid.getOrder({
orderId,
});
Le champ status
peut mettre un certain temps à quitter la valeur PENDING
. Les courbes de charge peuvent mettre quelques minutes à être renvoyées par Enedis.
status
passe à FAILED
, et que le champ error
renvoir un message du type “La demande ne peut aboutir : aucun service souscrit de courbe de charge n'est présent pour la période demandée”, cela signifie qu’Enedis a besoin de temps pour remonter vos données de consommation depuis le compteur Linky. En effet, il se peut que vous n’ayez jamais donné votre consentement auparavant, et dans ce cas Enedis ne remonte pas automatiquement les données qui sont stockées sur votre compteur.
Quand le champ status
passe à SUCCESS
, alors vous pouvez récupérer les données associées via la commande getRequestData
:
const { data } = await switchgrid.getRequestData({
requestId: requests[0].id,
period: "1h", // ou 30min, 15min, 10min
format: "csv"
})
Pour les requêtes de type LOADCURVE
, vous récupérez les données à un pas de temps fixe. Vous pouvez préciser à quel pas de temps. C’est l’utilité de l’argument period
.
Vous récupérez alors les données sous le format précisé.
startDate,powerInWatts
2022-10-03T22:00:00.000Z,159
2022-10-03T23:00:00.000Z,237
2022-10-04T00:00:00.000Z,538
2022-10-04T01:00:00.000Z,228
2022-10-04T02:00:00.000Z,250
2022-10-04T03:00:00.000Z,295
2022-10-04T04:00:00.000Z,327
2022-10-04T05:00:00.000Z,712
2022-10-04T06:00:00.000Z,450
2022-10-04T07:00:00.000Z,1077
2022-10-04T08:00:00.000Z,1272
2022-10-04T09:00:00.000Z,2278
2022-10-04T10:00:00.000Z,1821
2022-10-04T11:00:00.000Z,870
2022-10-04T12:00:00.000Z,564
2022-10-04T13:00:00.000Z,659
2022-10-04T14:00:00.000Z,373
2022-10-04T15:00:00.000Z,509
...
Resources complémentaires
- Vous pouvez consulter la documenation de notre API depuis votre espace app.switchgrid.tech
- Un guide y est aussi disponible pour démarrer.
Commencez à tirer le meilleur des données électriques de vos clients.