API documentatie
Met de EnergieID Web API koppel je je eigen applicaties en systemen aan EnergieID en ga je verder dan de integraties die we standaard aanbieden. Deze pagina is het startpunt voor elke API-integratie.
Alle endpoints staan beschreven in onze API-referentiedocumentatie (in het Engels). Moet je app alleen meterstanden naar een dossier sturen? Gebruik dan Inkomende Webhooks.
Authenticatie
EnergieID ondersteunt drie manieren om je aan te melden bij de Web API. Welke je kiest, hangt af van het type integratie:
- OAuth 2.0 voor client-apps die handelen namens gebruikers die zelf aanmelden en toestemming geven. Lees Een client-app aanmaken.
- Persoonlijke API-sleutels voor je eigen scripts en kleine automatiseringen.
- Workspace API-sleutels voor backend-integraties die eigendom zijn van een organisatie. Lees API-sleutels voor Workspaces.
Hoe je de juiste methode kiest, welke rechten elke methode geeft en hoe je een sleutel meestuurt in een verzoek, lees je in Authenticatie en API-sleutels.
Machtigingsscopes
Scopes bepalen tot welke objecten een token of sleutel toegang heeft en welke acties erop toegelaten zijn. Een scope bestaat uit het object, gevolgd door de actie, bijvoorbeeld records:write. Een scope met write geeft ook leestoegang.
Een OAuth-app vraagt de scopes aan die ze nodig heeft. De gebruiker ziet die scopes wanneer hij je app toestemming geeft. API-sleutels krijgen hun scopes automatisch, op basis van het type sleutel en het gekozen toegangsniveau.
| Scope | Korte beschrijving |
|---|---|
| profile:read | Alleen-leestoegang tot het profiel van de gebruiker. |
| profile:write | Lees- en schrijftoegang tot het profiel van de gebruiker. |
| records:read | Alleen-leestoegang tot de dossiers van de gebruiker. |
| records:write | Lees- en schrijftoegang tot de dossiers van de gebruiker. |
| workspaces:read | Alleen-leestoegang tot de Workspaces waar de gebruiker toegang toe heeft. |
| workspaces:write | Lees- en schrijftoegang tot de Workspaces waar de gebruiker toegang toe heeft. |
| groups:read | Alleen-leestoegang tot de groepen van de gebruiker. |
| groups:write | Lees- en schrijftoegang tot de groepen van de gebruiker. |
Wil je app toegang behouden wanneer de gebruiker niet actief is, vraag dan ook offline_access aan. Meer daarover lees je in Een client-app aanmaken.
Objectmodellen
Alle endpoints van de Web API geven gegevens terug in JSON-formaat.
Sommige endpoints geven vereenvoudigde versies van de objecten terug. Endpoints die meerdere objecten teruggeven, leveren doorgaans een lijst van vereenvoudigde objecten. Vereenvoudigde objecten bevatten altijd een id waarmee je de volledige details van het object kunt opvragen.
| Object | Korte beschrijving |
|---|---|
| Workspace | De centrale werkomgeving van een organisatie. Een Workspace bundelt dossiers, gebruikers, rollen, configuratie en integraties. |
| Record | Een record (dossier) stelt doorgaans een gebouw met een eigen adres voor. Records hebben een verzameling meters. |
| Meter | Meterobjecten stellen echte, fysieke stromen voor die gemeten kunnen worden. De metric van de meter beschrijft welke stroom gemeten wordt en waar in die stroom. Voor een beter overzicht zijn de meters ingedeeld in thema's. |
| Reading | Een reading (meting) is één datapunt in de stroom van de meter. Ze bestaat uit een timestamp, een waarde en een validatiecode. |
| Group | Een groep is een verzameling dossiers. Groepen worden vervangen door Workspaces: gebruik Workspaces voor nieuwe integraties. |
Datasets
Voor elk dossier berekenen we prestatie-indicatoren voor energie, water, afval en mobiliteit.
Je kunt resultaten opsplitsen en filteren op een van de ondersteunde dimensies. Gebruik één dimensie om te filteren en een andere om te groeperen.
| Naam | Beschrijving | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Energie | |||||||||||||||||||||
| energyEmissions |
Energie-emissies (kg) Meet de CO2-uitstoot van energie. Dimensies:
|
||||||||||||||||||||
| energyProduction |
Energieproductie (kWh) Meet de lokale energieproductie in kWh. Dimensies:
|
||||||||||||||||||||
| Water | |||||||||||||||||||||
| waterUse |
Waterverbruik (l) Meet het waterverbruik in liter. Dimensies:
|
||||||||||||||||||||
| Afval | |||||||||||||||||||||
| solidWaste |
Vast afval (kg) Bepaalt de hoeveelheid vast afval in kg. Dimensies:
|
||||||||||||||||||||
| Mobiliteit | |||||||||||||||||||||
| distanceTravelled |
Afgelegde afstand (km) Bepaalt de afgelegde afstand in km. Dimensies:
|
||||||||||||||||||||
Benchmark
De volgende benchmarkindicatoren zijn beschikbaar voor huishoudens en scholen.
Benchmarks zijn enkel beschikbaar als een minimum aantal gebruikers hun resultaten bijdraagt aan de berekening. Bovendien worden benchmarks alleen berekend voor kalenderjaren en -maanden.
| Naam | Beschrijving |
|---|---|
| energyEmissionsPerGsm |
Energie-emissies per m² (kg) Vergelijkt de dagelijkse CO2-uitstoot van energie per vierkante meter bruto-oppervlakte. |
| energyEmissionsPerOccupant |
Energie-emissies per bewoner (kg) Vergelijkt de dagelijkse CO2-uitstoot van energie per bewoner. |
| energyUsePerGsm |
Energieverbruik per m² (kWh) Vergelijkt het dagelijkse energieverbruik per vierkante meter bruto-oppervlakte. |
| energyUsePerOccupant |
Energieverbruik per bewoner (kWh) Vergelijkt het dagelijkse energieverbruik per bewoner. |
| waterUsePerOccupant |
Waterverbruik per bewoner (l) Vergelijkt het dagelijkse waterverbruik per bewoner. Momenteel wordt enkel drinkingWater ondersteund. |
Tijdzones
Bij sommige verzoeken kun je timestamps opgeven, of ze genereren timestamps met tijdzone-informatie. Die verzoeken gebruiken expliciet een ISO 8601-timestamp met tijdzone-informatie, bijvoorbeeld 2018-08-05T15:05:06+01:00.