Documentation des API

L'API Web d'EnergieID vous permet de connecter vos propres applications et systèmes à EnergieID et d'aller au-delà des intégrations que nous proposons par défaut. Cette page est le point de départ de toute intégration API.

Tous les endpoints sont décrits dans notre documentation de référence de l'API (en anglais). Votre application doit seulement envoyer des relevés de compteurs vers un dossier ? Utilisez alors le webhook entrant.

Authentification

EnergieID propose trois manières de s'authentifier auprès de l'API Web. Le choix dépend du type d'intégration :

OAuth 2.0 pour les applications clientes qui agissent au nom d'utilisateurs qui se connectent et donnent eux-mêmes leur consentement. Lisez Créer une application cliente.
Clés API personnelles pour vos propres scripts et petites automatisations.
Clés API de Workspace pour les intégrations backend qui appartiennent à une organisation. Lisez Clés API pour les Workspaces.

Comment choisir la bonne méthode, quels droits chaque méthode accorde et comment envoyer une clé avec une requête : tout est expliqué dans Authentification et clés API.

Scopes d'autorisation

Les scopes déterminent à quels objets un token ou une clé donne accès et quelles actions sont autorisées. Un scope se compose de l'objet suivi de l'action, par exemple records:write. Un scope write donne aussi un accès en lecture.

Une application OAuth demande les scopes dont elle a besoin. L'utilisateur voit ces scopes lorsqu'il donne son consentement. Les clés API reçoivent leurs scopes automatiquement, selon le type de clé et le niveau d'accès choisi.

Scope	Courte description
profile:read	Accès en lecture seule au profil de l'utilisateur.
profile:write	Accès en lecture et en écriture au profil de l'utilisateur.
records:read	Accès en lecture seule aux dossiers de l'utilisateur.
records:write	Accès en lecture et en écriture aux dossiers de l'utilisateur.
workspaces:read	Accès en lecture seule aux Workspaces auxquels l'utilisateur a accès.
workspaces:write	Accès en lecture et en écriture aux Workspaces auxquels l'utilisateur a accès.
groups:read	Accès en lecture seule aux groupes de l'utilisateur.
groups:write	Accès en lecture et en écriture aux groupes de l'utilisateur.

Si votre application doit conserver l'accès lorsque l'utilisateur n'est pas actif, demandez aussi offline_access. Plus d'informations dans Créer une application cliente.

Modèles d'objets

Tous les endpoints de l'API Web renvoient des données au format JSON.

Certains endpoints renvoient des versions simplifiées des objets. En général, les endpoints qui renvoient plusieurs objets fournissent une liste d'objets simplifiés. Les objets simplifiés contiennent toujours un id qui permet d'obtenir tous les détails de l'objet.

Objet	Courte description
Workspace	L'environnement de travail central d'une organisation. Un Workspace regroupe les dossiers, les utilisateurs, les rôles, la configuration et les intégrations.
Record	Un record (dossier) représente généralement un bâtiment avec sa propre adresse. Les records possèdent un ensemble de compteurs.
Meter	Les objets compteur représentent des flux physiques réels qui peuvent être mesurés. La metric du compteur décrit quel flux est mesuré et à quel endroit de ce flux. Pour une meilleure vue d'ensemble, les compteurs sont répartis en thèmes.
Reading	Un reading (relevé) est un point de données dans le flux du compteur. Il se compose d'un timestamp, d'une valeur et d'un code de validation.
Group	Un groupe est un ensemble de dossiers. Les groupes sont remplacés par les Workspaces : utilisez les Workspaces pour les nouvelles intégrations.

Datasets

Pour chaque dossier, nous calculons des indicateurs de performance pour l'énergie, l'eau, les déchets et la mobilité.

Vous pouvez ventiler et filtrer les résultats selon l'une des dimensions prises en charge. Utilisez une dimension pour filtrer et une autre pour regrouper.

Nom

Description

Énergie

energyEmissions

Émissions énergétiques (kg)

Mesure les émissions de CO2 liées à l'énergie.
Calcul : énergie fournie pondérée - énergie exportée pondérée
Pondération : facteurs d'émission de CO2 (de kWh en kg d'équivalent CO2)

Dimensions :

Nom	Type	Filtre	Regroupement	Valeurs prises en charge
carrier	string	Oui	Oui	biomass, butane, districtCooling, districtHeating, electricity, fuelOil, liquidGas, naturalGas, solarThermal
type	string	Oui	Oui	electric, nonElectric

energyProduction

Production d'énergie (kWh)

Mesure la production d'énergie sur site en kWh.
Calcul : production totale d'énergie

Dimensions :

Nom	Type	Filtre	Regroupement	Valeurs prises en charge
carrier	string	Oui	Oui	cogenElectricity, solarPhotovoltaic, solarThermal, wind
type	string	Oui	Oui	electric, nonElectric
meter	guid	Non	Oui	L'id de chaque compteur de production d'énergie.

Eau

waterUse

Consommation d'eau (l)

Mesure la consommation d'eau en litres.
Calcul : consommation d'eau totale

Dimensions :

Nom	Type	Filtre	Regroupement	Valeurs prises en charge
type	string	Oui	Oui	drinkingWater, groundwater, rainwater
meter	guid	Non	Oui	L'id de chaque compteur de consommation d'eau.

Déchets

solidWaste

Déchets solides (kg)

Détermine la quantité de déchets solides en kg.
Calcul : total des déchets solides

Dimensions :

Nom	Type	Filtre	Regroupement	Valeurs prises en charge
fraction	string	Oui	Oui	electronicWaste, glass, organicWaste, paperAndCardboard, pmd, residualWaste, softPlastics
type	string	Oui	Oui	biodegradable, recyclable, residual, special
meter	guid	Non	Oui	L'id de chaque compteur de déchets solides.

Mobilité

distanceTravelled

Distance parcourue (km)

Détermine la distance parcourue en km.
Calcul : distance totale parcourue

Dimensions :

Nom	Type	Filtre	Regroupement	Valeurs prises en charge
vehicleType	string	Oui	Oui	bike, car, motor, scooter
meter	guid	Non	Oui	L'id de chaque compteur de mobilité.

Benchmark

Les indicateurs de benchmark suivants sont disponibles pour les ménages et les écoles.

Les benchmarks ne sont disponibles que si un nombre minimum d'utilisateurs contribuent au calcul avec leurs résultats. De plus, les benchmarks ne sont calculés que pour des années et des mois calendaires.

Nom	Description
energyEmissionsPerGsm	Émissions énergétiques par m² (kg) Compare les émissions quotidiennes de CO2 liées à l'énergie par mètre carré de surface brute. Calcul : émissions quotidiennes moyennes de CO2 liées à l'énergie / surface brute totale Filtres par valeur : type d'énergie
energyEmissionsPerOccupant	Émissions énergétiques par occupant (kg) Compare les émissions quotidiennes de CO2 liées à l'énergie par occupant. Calcul : émissions quotidiennes moyennes de CO2 liées à l'énergie / nombre total de personnes Filtres par valeur : type d'énergie
energyUsePerGsm	Consommation d'énergie par m² (kWh) Compare la consommation quotidienne d'énergie par mètre carré de surface brute. Calcul : consommation quotidienne moyenne d'énergie / surface brute totale Filtres par valeur : type d'énergie
energyUsePerOccupant	Consommation d'énergie par occupant (kWh) Compare la consommation quotidienne d'énergie par occupant. Calcul : consommation quotidienne moyenne d'énergie / nombre total de personnes Filtres par valeur : type d'énergie
waterUsePerOccupant	Consommation d'eau par occupant (l) Compare la consommation quotidienne d'eau par occupant. Calcul : consommation quotidienne moyenne d'eau / nombre total de personnes Filtres par valeur : type d'eau Pour l'instant, seul drinkingWater est pris en charge.

Fuseaux horaires

Certaines requêtes permettent d'indiquer des timestamps ou génèrent des timestamps avec des informations de fuseau horaire. Ces requêtes utilisent explicitement un timestamp ISO 8601 avec fuseau horaire, par exemple 2018-08-05T15:05:06+01:00.