WattWanneer API

Dynamische energieprijsvoorspellingen voor je eigen huis, laadpaal of thuisbatterij

Elke andere bron stopt bij morgen. Wij gaan zeven dagen vooruit.

Day-ahead-bronnen zoals ENTSO-E, Tibber of de app van je eigen leverancier geven je de uurprijzen tot en met morgen, zodra de EPEX-veiling rond 13:00 is afgelopen. Daarmee kun je plannen wat vandaag of morgen moet gebeuren. WattWanneer geeft je diezelfde gepubliceerde marktprijzen én zes dagen voorspelling erachter, in één reeks van 168 uur. Dat is het verschil tussen weten wanneer je vandaag het beste laadt, en weten wélk blok in de komende week het goedkoopst is. En dat blok zit niet altijd waar je het verwacht: in de zomer is het vaak de middag, als de zon de prijs naar beneden duwt, en in de winter juist de nacht.

Twee van deze zeven vragen kun je met day-ahead beantwoorden. Voor de andere vijf moet je verder kunnen kijken dan morgen, en dan is er in Nederland geen andere bron die dat geeft.

Wat het scheelt, gerekend met onze eigen prijsdata over 2025 en 2026: binnen één week zit gemiddeld 5 cent per kWh verschil tussen het goedkoopste laadmoment van de week en dat van een willekeurige dag. Op een laadsessie van 40 kWh is dat twee euro, en bij twee sessies per week loopt dat op tot ongeveer 200 euro per jaar. Het abonnement kost 60 euro per jaar.

De eerste 24 uur van onze reeks zijn de echte, gepubliceerde marktprijzen, herkenbaar aan het veld source. Daarna begint het model, en hoe goed dat het doet meten we dagelijks tegen de gerealiseerde prijzen. Die cijfers staan live in de technische documentatie en zijn zelf op te vragen via /v1/metrics. Acht JSON-endpoints, beveiligd met API-keys.

Ontworpen voor professionele energie-automatisering

De WattWanneer API is geschikt voor elke toepassing die afhankelijk is van dynamische energieprijzen. Slimme batterijopslag, EV-laadsystemen, warmtepompen, boilers en domotica kunnen met onze 168-uurs forecast exact bepalen wanneer energie gunstig of ongunstig is. Zo bouw je moeiteloos logica voor goedkoop laden, peak-shaving, load-shifting en geoptimaliseerd bufferen. Onze gestandaardiseerde JSON-structuur maakt integratie eenvoudig en betrouwbaar. Bouw je hiermee een dienst voor anderen, dan hoort daar een zakelijk abonnement bij: zie WattWanneer Zakelijk.

Zakelijk gebruik

Snel starten

1. Gebruik als base URL: https://wattwanneer.nl/api/v1
2. Stuur je ontvangen API-key mee als header: X-API-Key: JOUW_API_KEY
3. Test eerst met een kleine forecast-call voordat je automations aansluit.

curl -H "X-API-Key: JOUW_API_KEY" "https://wattwanneer.nl/api/v1/forecast?hours=24"

Alle timestamps zijn UTC. Een 401 betekent dat de key ontbreekt of ongeldig is. Een 429 betekent dat de rate limit tijdelijk is bereikt.

Responsevoorbeelden

Drie voorbeelden om de vorm te zien. Wil je van elk endpoint alle velden weten, met type en betekenis? Dat staat compleet in de technische documentatie.

{
  "zone": "NL",
  "generated_at": "2026-07-02T06:42:00Z",
  "model_version": "hist_gradient_boosting",
  "horizon_hours": 24,
  "points": [
    {
      "timestamp": "2026-07-02T22:00:00Z",
      "price_eur_per_kwh": 0.0999,
      "confidence_low": 0.0592,
      "confidence_high": 0.1406,
      "source": "model"
    }
  ]
}

{
  "zone": "NL",
  "generated_at": "2026-07-02T06:42:00Z",
  "cheapest_hours_next_24h": [
    "2026-07-03T11:00:00Z",
    "2026-07-03T12:00:00Z",
    "2026-07-03T10:00:00Z"
  ],
  "cheapest_window": {
    "window_hours": 3,
    "start": "2026-07-03T10:00:00Z",
    "end": "2026-07-03T12:00:00Z",
    "end_exclusive": "2026-07-03T13:00:00Z",
    "avg_price": -0.0316
  },
  "average_price_next_24h": 0.0806,
  "average_price_next_7d": 0.1045,
  "expected_peak_price_next_7d": 0.3028
}

{
  "model_version": "hist_gradient_boosting",
  "mae_eur_per_kwh": 0.0124,
  "r2": 0.92,
  "n_samples": 95258,
  "last_backtest_range": {
    "from": "2026-05-14",
    "to": "2026-05-21"
  }
}

Vijf usecases: van zonnepaneel tot thuisbatterij

curl -H "X-API-Key: JOUW_API_KEY" \
  "https://wattwanneer.nl/api/v1/tariff?charges=0.12&vat=21"

[
  { "start": "2026-07-10T00:00:00Z", "end": "2026-07-10T01:00:00Z", "value": 0.312 },
  ...
]

curl -H "X-API-Key: JOUW_API_KEY" \
  "https://wattwanneer.nl/api/v1/battery-plan?capacity_kwh=10&power_kw=5&efficiency=0.9"

{ "days": [ {
    "date": "2026-07-10",
    "charge_hours": ["2026-07-10T11:00:00Z", "2026-07-10T12:00:00Z"],
    "avg_charge_price": 0.0113,
    "discharge_hours": ["2026-07-10T18:00:00Z", "2026-07-10T19:00:00Z"],
    "avg_discharge_price": 0.1499,
    "spread_eur_per_kwh": 0.1386,
    "estimated_profit_eur": 1.21,
    "worth_cycling": true
  }, ... ],
  "best_day": "2026-07-14" }

curl -H "X-API-Key: JOUW_API_KEY" \
  "https://wattwanneer.nl/api/v1/cheapest-hours?count=6"

curl -H "X-API-Key: JOUW_API_KEY" \
  "https://wattwanneer.nl/api/v1/negative-hours?threshold=0"

curl -H "X-API-Key: JOUW_API_KEY" \
  "https://wattwanneer.nl/api/v1/history?days=7"

Voorbeeld API-aanroepen

Gebruik steeds de header X-API-Key: <JOUW_KEY>.

curl -H "X-API-Key: JOUW_API_KEY" "https://wattwanneer.nl/api/v1/forecast?hours=168"

curl -H "X-API-Key: JOUW_API_KEY" "https://wattwanneer.nl/api/v1/summary?windowHours=3"

fetch("https://wattwanneer.nl/api/v1/forecast?hours=168", {
  headers: { "X-API-Key": "JOUW_API_KEY" }
})
  .then((res) => res.json())
  .then((data) => console.log(data));

Base URL: https://wattwanneer.nl/api/v1/
Header:    X-API-Key: JOUW_API_KEY
Rate limit: 10 req/min per key

Home Assistant koppelen

De meest voorkomende use-case voor de WattWanneer API is automatische sturing van apparaten via Home Assistant: vaatwasser, EV, boiler, warmtepomp of thuisbatterij die zelf weten wanneer stroom goedkoop is.

Het snelst gaat dat met onze Home Assistant-integratie. Voeg hercozandwijk/wattwanneer-homeassistant in HACS toe als custom repository, vul je API-key in en je hebt zeven sensoren zonder configuratiewerk: huidige prijs, prijs volgend uur, gemiddelde, laagste en hoogste van vandaag, het goedkoopste venster en het weekgemiddelde met de volledige reeks als attribuut. De integratie is ingediend voor de standaard HACS-lijst; tot die aanvraag is beoordeeld gaat het via de custom-repository-route. Uitleg staat in onze blogpost.

Wil je het liever zelf opbouwen, dan werkt de handmatige setup hieronder onverminderd.

1. Sensor met de eerstvolgende forecastprijs

De /v1/forecast endpoint geeft de komende forecasturen terug. Deze REST sensor toont de eerstvolgende prijs en bewaart de timestamp als attribuut:

sensor:
  - platform: rest
    name: "WattWanneer eerstvolgende prijs"
    resource: "https://wattwanneer.nl/api/v1/forecast?hours=24"
    method: GET
    headers:
      X-API-Key: "JOUW_API_KEY"
    value_template: "{{ value_json.points[0].price_eur_per_kwh | float }}"
    json_attributes_path: "$.points[0]"
    json_attributes:
      - timestamp
      - confidence_low
      - confidence_high
      - source
    unit_of_measurement: "EUR/kWh"
    scan_interval: 1800

2. Goedkoopste N-uurs venster vooruit

De /v1/summary endpoint rekent het goedkoopste N-uurs venster kant-en-klaar uit. Geen template-logica nodig:

sensor:
  - platform: rest
    name: "Goedkoopste 2-uurs venster start"
    resource: "https://wattwanneer.nl/api/v1/summary?windowHours=2"
    method: GET
    headers:
      X-API-Key: "JOUW_API_KEY"
    value_template: "{{ value_json.cheapest_window.start }}"
    json_attributes_path: "$.cheapest_window"
    json_attributes:
      - start
      - end
      - end_exclusive
      - avg_price
      - window_hours
    scan_interval: 1800

De sensor-state is nu de starttijd (ISO-timestamp) van het goedkoopste 2-uurs venster in de komende 24 uur. Voor andere lengtes pas je windowHours aan (ondersteund: 1 t/m 24).

3. Automation: vaatwasser op het goedkoopste 2-uurs venster

Trigger een apparaat exact op de starttijd van het venster:

automation:
  - alias: "Vaatwasser starten op goedkoopste 2-uurs venster"
    trigger:
      - platform: time_pattern
        minutes: "/1"
    condition:
      - condition: template
        value_template: >-
          {% set start = as_timestamp(states('sensor.goedkoopste_2_uurs_venster_start')) %}
          {{ start is number and start <= as_timestamp(now()) < start + 60 }}
      - condition: state
        entity_id: input_boolean.vaatwasser_gereed
        state: "on"
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.vaatwasser_stekker
      - service: input_boolean.turn_off
        target:
          entity_id: input_boolean.vaatwasser_gereed

Veelgebruikte automations

• EV laden: 3-uurs venster, ~7-10 kWh per nacht. Schakelt de laadpaal of stuurt de OCPP-instructie via de Easee, Zaptec of Wallbox-integratie.
• Vaatwasser of wasmachine: 1-2 uurs venster, getrigger via slimme stekker of Miele/Bosch-integratie.
• Boiler / elektrisch warm water: 1 uurs venster is genoeg om de tank op te warmen.
• Warmtepomp opwarmcyclus: 5-uurs venster met setpoint-verhoging.
• Thuisbatterij: combineer met je inverter (Sonnen, GrowAtt, SolarEdge) en het venster-endpoint om laad- en ontlaadmomenten te plannen.

Verdienmodel: rekent zich snel terug

Een gemiddeld huishouden met EV, vaatwasser, wasmachine en boiler bespaart 150 tot 400 euro per jaar door slim te schakelen op de goedkoopste uren. De API kost €4,99 per maand (10.000 requests, ruim genoeg voor automations die elke 30 minuten pollen). Dat is binnen de eerste maand terugverdiend.

Veelgestelde vragen over de API en Home Assistant

Toch nog meer API technische informatie nodig?

Zie de technische documentatie voor alle velden per endpoint, met type, eenheid en betekenis. Daar staat ook wat de conventies zijn (tijdstempels in UTC, prijzen in euro per kWh, en wanneer een prijs vaststaat of nog een voorspelling is), plus een tabel die per soort logica aangeeft welk endpoint en welke velden je nodig hebt. Bouw je een eigen energiemanager, dan is dat de pagina om open te houden.

Transparantie & nauwkeurigheid

De nauwkeurigheid is transparant opvraagbaar: via /v1/metrics haal je de modelkwaliteit op, zoals de MAE (gemiddelde afwijking), R², het aantal datapunten en de laatste backtest-range. De MAE ligt doorgaans rond de 1 tot 2,5 cent per kWh, afhankelijk van de marktvolatiliteit. Het model traint op ruim 95.000 uur historische EPEX-data en wordt dagelijks opnieuw getraind.

Disclaimer

De gegevens die WattWanneer verstrekt, inclusief de 168-uurs prijsvoorspelling, samenvattende inzichten en modelmetrics, zijn gebaseerd op historische marktgegevens en een voorspellend model. Hoewel we streven naar een zo betrouwbaar mogelijke forecast, kunnen afwijkingen en onjuiste prijzen voorkomen door marktvolatiliteit, datavertragingen of modelbeperkingen. WattWanneer kan niet aansprakelijk worden gesteld voor beslissingen, kosten, schade of automatiseringen die voortkomen uit het gebruik van deze data. Gebruik de informatie als indicatie en combineer deze waar nodig met eigen controles of aanvullende bronnen.