API | Slimverbruik

Welkom bij onze API, ontworpen om je te helpen bij het vinden van het meest gunstige moment om energie te verbruiken.

Of je nu wilt optimaliseren op basis van:

CO₂-uitstoot
duurzame energieproductie
energieprijzen
of een combinatie van deze drie

Onze API biedt eenvoudige en efficiënte oplossingen.

Autorisatie gebeurt via een API-sleutel, die je van ons krijgt. Tijdens de pilotfase heb je onbeperkt toegang tot alle functionaliteiten. Daarnaast hebben we uitgebreide documentatie beschikbaar, inclusief Swagger en Redoc, om je te ondersteunen bij de integratie.

Wat kun je nou precies met de API?
Hoe werkt de API?
Hoe kom ik aan een API key?
Welke endpoints zijn er?
Documentatie
TLDR; Developer

Wat kun je nou precies met de API?

Enkele praktische voorbeelden:

Laad je auto op het meest gunstige moment. Met onze API kun je je laadpaal eenvoudig instellen om je auto op te laden wanneer de stroomkosten het laagst zijn. Dit kan per kwartier of per uur worden ingesteld. Als er bijvoorbeeld gunstige tijdvakken zijn van 13:00 tot 14:00 en van 16:00 tot 17:00, dan kan onze API automatisch je laadpaal inschakelen (en uitschakelen) op deze momenten. Uiteraard moet hiervoor je laadpaal en/of auto wel geschikt voor zijn
Zet je wasmachine op het juiste moment aan. Bespaar op je energiekosten en draag bij aan een beter milieu door je wasmachine automatisch te laten draaien op de meest voordelige tijden. Vul 's ochtends je wasmachine, ga na het werk naar huis en laat hem op het beste moment starten, zodat je altijd profiteert van lagere tarieven.
Plan je warmte- of koelinstallatie: Heb je een luchtverhitter, warmtepomp of airco? Met deze API kun je deze apparaten laten draaien op de tijden dat de stroom het goedkoopst is, zodat je comfortabel bent zonder onnodig te veel te betalen.
Crypto minen: Ga alleen minen op de voordeligste uren van de dag, of stel een filter in op de uurprijs, zodat je alleen gaat minen vanaf of tot een bepaalde uurprijs.

Hoe werkt de API?

De API berekent op basis van jouw voorspellings start- en eindtijd wat het beste moment is om te besparen binnen dat kader. De duur van het beste moment is door jou zelf instelbaar (via de parameter 'device_run_time'), wil je dat je apparaat zo lang mogelijk aanstaat, of wil je de best mogelijke momenten weten en dat het apparaat alleen op deze momenten aangaat? Het kan allemaal!

Over het algemeen is het zo, hoe korter de 'device_run_time' hoe groter de relatieve potentiële besparing, omdat we dan beter de draaitijd van het apparaat kunnen matchen op het beste moment.

De predictions API kun je aanroepen door een GET te doen op het '/api/v1/predictions' endpoint. In de sectie over de API parameters kun je zien welke parameters verplicht zijn. Om een prediction te verkrijgen heb je een collectie (collection) en device (apparaat) nodig. Een collection bestaat uit 1 of meerdere devices. Iedereen heeft standaard 1 collection (Default collection), maar je kan meerdere collections aanmaken. Hiermee kun je devices makkelijk groeperen en aanroepen.

Een device kun je aanmaken door een POST te doen op het 'api/v1/devices' endpoint, als je geen collection_id opgeeft, word het nieuwe device automatisch gekoppeld aan de default collection.

De base-url van de API is: https://api.slimverbruik.nl

Hoe kom ik aan een API key?

Vul het pilot formulier en we nemen z.s.m. contact met je op, in de toekomst word het mogelijk om zelf je API keys aan te maken, wijzigen of te verwijderen.

Welke entiteiten zijn er?

Bij het gebruik van de API zijn er een aantal entiteiten, hieronder een opsomming van de entiteiten en wat ze inhouden:

Collections

Een collection kan 1 of meerdere devices bevatten, elke gebruiker heeft minimaal 1 collections ('Default collection'). Een collection heeft als doel om devices te kunnen groeperen.

Devices

Een 'device' is een apparaat wat je ook daadwerkelijk in- of uitschakelt, omdat elk apparaat uniek is qua verbruik of 'device_run_time' (hoe lang wil je het apparaat aan laten staan), heb je hier de keuze om meerdere devices aan te kunnen maken. Een device is altijd gekoppeld aan een collection.

Profiles

Een profiel is bedoeld om vooraf gedefinieerde instellingen alvast gereed te zetten zodat je dit niet elke keer in een API call hoeft te doen, en voor het geval dat je meerdere devices hebt die altijd hetzelfde profiel qua input parameters hebt, je kan dan met 1 wijziging het profiel wijzigen voor alle devices. Het is niet verplicht om een profiel te koppelen aan een device tenzij je het apparaat wilt schakelen via onze webhooks.

Webhooks

Met het aanmaken van een webhook kun je een signaal van ons krijgen om een apparaat aan- en uit te schakelen. Wij maken dan een call naar een door jouw opgegeven endpoint voor de start actie en de stop actie. Hierdoor heb je geen omkijken meer en hoef je niets meer handmatig te doen.

Bij het aanmaken van 'webhooks' kun je ook de parameter 'calls' invullen, dit houdt in hoe vaak we het apparaat mogen aanroepen. Dit is intermitterend. Als je dus 3 invult, gaan wij in de door jouw geselecteerde periode 3x jouw apparaat aanroepen. Als je dit gebruikt vervalt de waarde 'device_run_time' en wordt deze vervangen door de waarde die je bij 'granulariteit' in de profiel entiteit hebt ingevuld. Dit is 15m of een uur.

Filters

Met filters kun je bepalen vanaf welke waardes je resultaten terug wilt hebben, wil je bijvoorbeeld alleen resultaten terugkrijgen bij negatieve uurprijzen? Vul dan als 'max' waarde 0 in en jouw apparaat wordt alleen getriggerd op basis van jouw voorwaarden!

Welke endpoints zijn er?

Onze API kent verschillende endpoints

Entiteit	Methode	Endpoint	Functie
Predictions	GET	/api/v1/predictions	Het verkrijgen van een voorspelling met de ingevoerde parameters
	GET	/api/v1/predictions/time-span	Het verkrijgen van het maximale prediction window
Collections	GET	/api/v1/collections	Een overzicht van alle collections behorende bij de gebruiker
	POST	/api/v1/collections	Het aanmaken van een nieuwe collectie
	PATCH	/api/v1/collections/{collection_id}	Het wijzigen van een collectie
	DELETE	/api/v1/collections/{collection_id}	Het verwijderen van een collectie
Devices	GET	/api/v1/devices	Een overzicht van alle devices per collection behorende bij de gebruiker
	POST	/api/v1/devices	Het aanmaken van een nieuwe device
	PATCH	/api/v1/devices/{device_id}	Het wijzigen van een device
	DELETE	/api/v1/devices/{device_id}	Het verwijderen van een device
Profiles	GET	/api/v1/profiles	Een overzicht van alle profiles behorende bij de gebruiker
	POST	/api/v1/profiles	Het aanmaken van een nieuw profiel
	POST	/api/v1/profiles/{profile_id}/filter/{filter_id}	Een filter koppelen aan een profiel
	PATCH	/api/v1/profiles/{profile_id}	Het wijzigen van een profiel
	DELETE	/api/v1/profiles/{profile_id}	Het verwijderen van een profiel
	DELETE	/api/v1/profiles/{profile_id}/filter/{filter_id}	Een filter loskoppelen van een profiel
Webhooks	GET	/api/v1/webhooks	Een overzicht van alle webhooks behorende bij de gebruiker
	POST	/api/v1/webhooks	Het aanmaken van een nieuwe webhook
	PATCH	/api/v1/webhooks/{webhook_id}	Het wijzigen van een webhook
	DEL	/api/v1/webhooks/{webhook_id}	Het verwijderen van een webhook
Filters	GET	/api/v1/filters	Een overzicht van alle filters behorende bij de gebruiker
	POST	/api/v1/filters	Het aanmaken van een filter
	PATCH	/api/v1/filters/{filter_id}	Het wijzigen van een filter
	DEL	/api/v1/filters/{filter_id}	Het verwijderen van een filter

Uitleg over de verschillende parameters in de requests

GET /api/v1/predictions

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Query	Datetime	prediction_window_start	Optioneel	Het start moment van het prediction window (over welke periode wil je het beste moment weten?)	2025-04-30T13:00	Default waarde is het eerst mogelijke startmoment
Query	Datetime	prediction_window_start	Optioneel	Het eind moment van het prediction window (over welke periode wil je het beste moment weten?)	2025-04-30T18:00	Default waarde is het laatst mogelijke eindmoment
Query	integer	device_id	Verplicht	Het unieke Id van een device	3
Query	Integer	device_run_time	Optioneel	Indicatie over hoe lang je energie wilt besparen (hoe lang staat je device aan?)	45	Default waarde komt overeen met de gekozen granulariteit (15m of 60m)
Query	Integer	emission_percentage	Verplicht	Aandeel van de emissiefactor in de uiteindelijke ranking (hoe hoger hoe belangrijker)	50	Waarde moet tussen 0 en 100 liggen
Query	Integer	price_percentage	Verplicht	Aandeel van de prijs in de uiteindelijke ranking (hoe hoger hoe belangrijker)	30	Waarde moet tussen 0 en 100 liggen
Query	Integer	renewable_percentage	Verplicht	Aandeel van de productie hernieuwbare energie in de uiteindelijke ranking (hoe hoger hoe belangrijker)	20	Waarde moet tussen de 0 en 100 liggen
Query	Integer	granularity	Verplicht	Geeft aan met welke granularity je wil werken	4	4: 15 minuten 5: 1 uur
Query	Boolean	switch	Verplicht	Geeft aan of je een lijst met resultaten terugkrijgt, of dat je alleen het beste moment terug wilt krijgen	True

/api/v1/predictions/time-span

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Query	integer	granularity	Verplicht	Geeft aan met welke granularity je wil werken	5	4: 15 minuten 5: 1 uur

POST /api/v1/collections/

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Body	String	collection_name	Verplicht	Unieke naam van de collectie	'Domotica'
Body	String	collection_description	Verplicht	Omschrijving van de collectie	'Apparaten welke slim aangestuurd kunnen worden'

PATCH /api/v1/collections/{collection_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	collection_id	Verplicht	Id van de collectie	4	Parameter is onderdeel van de URL
Body	String	collection_name	Optioneel	Unieke naam van de collectie	'Domotica'
Body	String	collection_description	Optioneel	Omschrijving van de collectie	'Apparaten welke slim aangestuurd kunnen worden'

DELETE /api/v1/collections/{collection_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	collection_id	Verplicht	Id van de collectie	3	Parameter is onderdeel van de URL

POST /api/v1/devices/

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Body	String	device_name	Verplicht	Unieke naam van het device	'Wasmachine'
Body	String	device_description	Verplicht	Omschrijving van het device	'Wasmachine op zolder'
Body	Integer	device_power	Verplicht	Vermogen van het apparaat	1000	Eenheid in Watt
Body	Integer	collection_id	Optioneel	Onder welke collection valt het device	4	Bij het ontbreken van de collection_id wordt het device toegekend aan de 'default collection'

PATCH /api/v1/devices/{devices_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	device_id	Verplicht	Id van het device	4	Parameter is onderdeel van de URL
Body	String	device_name	Optioneel	Unieke naam van het device	'Warmtepomp'
Body	String	device_description	Optioneel	Omschrijving van het device	'Slimme warmtepomp op zolder'
Body	String	device_power	Optioneel	Vermogen van het apparaat	1500	Eenheid in Watt
Body	Integer	collection_id	Optioneel	Onder welke collection valt het device?	5

DELETE /api/v1/device/{device_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	device_id	Verplicht	Id van het device	3	Parameter is onderdeel van de URL

POST /api/v1/profiles/

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Body	String	profile_name	Verplicht	Unieke naam van het profiel	'Keukenapparatuur profiel'
Body	String	profile_description	Verplicht	Omschrijving van het profiel	'Profiel voor alle keukenapparaten'
Body	String	prediction_range_start	Verplicht	Starttijd van prediction window	08:00	Dagelijks start moment van de tijdsduur waarin de prediction valt
Body	String	prediction_range_end	Verplicht	Eindttijd van prediction window	14:00	Dagelijks eind moment van de tijdsduur waarin de prediction valt
Body	Integer	granularity	Verplicht	Geeft aan met welke granulariteit je wilt werken	4	4: 15 minuten 5: 1 uur
Body	Integer	emisisonfactor_percentage	Verplicht	Aandeel emissiefactor op totale ranking	33	Dit bepaalt het aandeel van de emissiefactor rank in de totale rank
Body	Integer	renewable_percentage	Verplicht	Aandeel hernieuwebare energie op totale ranking	34	Dit bepaalt het aandeel de hoeveel hernieuwbare energie rank in de totale rank
Body	Integer	price_percentage	Verplicht	Aandeel stroom prijs op totale ranking	33	Dit bepaalt het aandeel van de prijs rank in de totale rank. De som van deze parameters moet altijd 100% zijn
Body	integer	device_run_time	Optioneel	Hoe lang gaat het apparaat verbruiken	90	Deze parameter heeft invloed op het bepalen van het beste moment. Bij ontbreken wordt de waarde v.d. gekozen granulariteit gebruikt (15 of 60 minuten)

POST /api/v1/profile/{profile_id}/filter/{filter_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	profile_id	Verplicht	Id van het profiel	3	Parameter is onderdeel van de URL
URL	Integer	filter_id	Verplicht	Id van het filter	3	Parameter is onderdeel van de URL

PATCH /api/v1/profiles/{profiles_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Body	String	profile_name	Verplicht	Unieke naam van het profiel	'Keukenapparatuur profiel'
Body	String	profile_description	Verplicht	Omschrijving van het profiel	'Profiel voor alle keukenapparaten'
Body	Integer	prediction_range_start	Verplicht	Starttijd van prediction window	08:00	Dagelijks start moment van de tijdsduur waarin de prediction valt
Body	Integer	prediction_range_end	Verplicht	Eindttijd van prediction window	14:00	Dagelijks eind moment van de tijdsduur waarin de prediction valt
Body	Integer	granularity	Verplicht	Geeft aan met welke granulariteit je wilt werken	4	4: 15 minuten 5: 1 uur
Body	Integer	emisisonfactor_percentage	Verplicht	Aandeel emissiefactor op totale ranking	33	Dit bepaalt het aandeel van de emissiefactor rank in de totale rank
Body	Integer	renewable_percentage	Verplicht	Aandeel hernieuwebare energie op totale ranking	34	Dit bepaalt het aandeel de hoeveel hernieuwbare energie rank in de totale rank
Body	Integer	price_percentage	Verplicht	Aandeel stroom prijs op totale ranking	33	Dit bepaalt het aandeel van de prijs rank in de totale rank. De som van deze parameters moet altijd 100% zijn
Body	integer	device_run_time	Optioneel	Hoe lang gaat het apparaat verbruiken	90	Deze parameter heeft invloed op het bepalen van het beste moment. Bij ontbreken wordt de waarde v.d. gekozen granulariteit gebruikt (15 of 60 minuten)

DELETE /api/v1/profile/{profile_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	profile_id	Verplicht	Id van het profiel	3	Parameter is onderdeel van de URL

DELETE /api/v1/profile/{profile_id}/filter/{filter_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	profile_id	Verplicht	Id van het profiel	3	Parameter is onderdeel van de URL
URL	Integer	filter_id	Verplicht	Id van het filter	3	Parameter is onderdeel van de URL

POST /api/v1/webhooks/

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Body	String	device_id	Verplicht	ID van het bijbehorende device	4
Body	String	start_endpoint	Verplicht	Endpoint wat door slimverbruik.nl word aangeroepen	https://mydevice.nl?action=start	Dit endpoint word aangeroepen zodra het beste moment is aangebroken
Body	String	stop_endpoint	Verplicht	Endpoint wat door slimverbruik.nl word aangeroepen	https://mydevice.nl?action=stop	Dit endpoint wordt aangeroepen zodra het beste moment is geëindigd
Body	Boolean	enabled	Verplicht	Is deze webhook actief	True
	Integer	calls	Optioneel	Hoe vaak mogen we je device aanroepen?	3	Default staat op 1, in dit voorbeeld roepen we je device 3x aan en uit (rekening houdende met de opgegeven granulariteit)
	Boolean	merge_consecutive_moments	Optioneel	Moeten we aaneen sluitende momenten samenvoegen?	True	Default staat op True. Dit houdt in dat er van 2 of meer aaneensluitende momenten (bijv 12:00-13:00 en 13:00-14:00) er 1 moment van wordt gebruikt. In dit voorbeeld wordt je device dus maar 1x aangestuurd i.p.v. 2x

PATCH /api/v1/webhooks/{webhooks_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Body	Integer	device_id	Verplicht	ID van het bijbehorende device	4
Body	String	start_endpoint	Verplicht	Endpoint wat door slimverbruik.nl word aangeroepen	https://mydevice.nl?action=start	Dit endpoint word aangeroepen zodra het beste moment is aangebroken
Body	String	stop_endpoint	Verplicht	Endpoint wat door slimverbruik.nl word aangeroepen	https://mydevice.nl?action=stop	Dit endpoint wordt aangeroepen zodra het beste moment is geëindigd
Body	Boolean	enabled	Verplicht	Is deze webhook actief	True
	Integer	calls	Optioneel	Hoe vaak mogen we je device aanroepen?	3	Default staat op 1, in dit voorbeeld roepen we je device 3x aan en uit (rekening houdende met de opgegeven granulariteit)
	Boolean	merge_consecutive_moments	Optioneel	Moeten we aaneen sluitende momenten samenvoegen?	True	Default staat op True. Dit houdt in dat er van 2 of meer aaneensluitende momenten (bijv 12:00-13:00 en 13:00-14:00) er 1 moment van wordt gebruikt. In dit voorbeeld wordt je device dus maar 1x aangestuurd i.p.v. 2x

DELETE /api/v1/webhook/{webhook_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	webhook_id	Verplicht	Id van de webhook	3	Parameter is onderdeel van de URL

POST /api/v1/filters/

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Body	String	strategy	Verplicht	Strategie omschrijving	'renewable'	renewable emission price
Body	Boolean	show_when_triggered	Verplicht	Wat moet zichtbaar zijn als het filter een match heeft	True	Bij de waarde 'True' worden alle resultaten teruggegeven die matchen aan het filter. Bij 'False' worden deze resultaten verborgen
Body	Float	min	Conditioneel ptioneel	Minimale waarde van het filter	-10	Minimale waarde voor het filter. Is verplicht als er geen max waarde is ogpegeven
Body	Float	max	Conditioneel optioneel	Maximale waarde van het filter	40	Maximale waarde voor het filter. Is verplicht als er geen min waarde is opgegeven.

PATCH /api/v1/filter/{filter_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
Body	String	strategy	Verplicht	Strategie omschrijving	'renewable'	renewable emission price
Body	Boolean	show_when_triggered	Verplicht	Wat moet zichtbaar zijn als het filter een match heeft	True	Bij de waarde 'True' worden alle resultaten teruggegeven die matchen aan het filter. Bij 'False' worden deze resultaten verborgen
Body	Float	min	Conditioneel optioneel	Minimale waarde van het filter	-10	Minimale waarde voor het filter. Is verplicht als er geen max waarde is ogpegeven
Body	Float	max	Conditioneel optioneel	Maximale waarde van het filter	40	Maximale waarde voor het filter. Is verplicht als er geen min waarde is opgegeven.

DELETE /api/v1/filters/{filter_id}

Locatie	Type	Naam	Verplicht?	Omschrijving	Voorbeeld	Opmerkingen
URL	Integer	filter_id	Verplicht	Id van het filter	3	Parameter is onderdeel van de URL

Documentatie

Onze API voldoet aan de OpenAPI Specificatie (OAS) en is daarom makkelijk te gebruiken.

TLDR; Developer

Base URL: https://api.slimverbruik.nl
Autorisatie: api-key in header: 'X-API-KEY'
Documentatie: https://api.slimverbruik.nl/docs

Hoe werkt het?

Slimverbruik API