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.

⚠️Vous devez être le titulaire, ou mandaté par le titulaire du contrat d’électricité lié à ce point, pour pouvoir demander les données et continuer ce tutoriel.

✅J’ai une clef d’API, et j’ai renseigné mon PDL sur mon espace.

2. Installez le SDK (5 min)

👉Vous utilisez un autre langage que Javascript ? Vous pouvez utiliser la spécification OpenAPI 3.1 dans votre langage, ou notre collection postman, ou directement faire les requêtes HTTP en suivant notre Guide dans votre espace Switchgrid.

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 consentement
consentCollectionMedium permet de décrire la façon dont on veut récupérer le consentement, en l’occurence un simple formulaire web
scopesAndPurpose permet de décrire les autorisations que l’on demande au signer, 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 valeur ADDRESS_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 champ consentCollectionDetails 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

✅J’ai signé le consentement, et j’ai noté l’askId.

👉Si vous avez perdu l’id d’un 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.

👉Si le 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.