WattWanneer API

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.

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. 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 knop hieronder opent je eigen Home Assistant en zet de integratie klaar in HACS. Met de hand kan ook: voeg hercozandwijk/wattwanneer-homeassistant toe als custom repository. De integratie is ingediend voor de standaard HACS-lijst, en tot die aanvraag is beoordeeld gaat het op deze manier. Uitleg staat in onze blogpost.

Toevoegen aan HACS

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

Eén valkuil hierbij. Deze automation vuurt precies op de starttijd van het venster. Ligt dat venster al achter je, dan gebeurt er de rest van de dag niets meer. Dat komt doordat /v1/summary rekent over de eerste 24 punten van de reeks, en die reeks begint bij middernacht van de dag waarop de voorspelling is gedraaid. ’s Zomers merk je dat nauwelijks, want de zon duwt het goedkoopste blok naar de middag. In januari 2026 lag het goedkoopste 3-uursvenster op 29 van de 31 dagen al vóór 12:00. Zet je die ochtend je vaatwasser klaar, dan draait hij niet.

Wil je een venster dat gegarandeerd nog moet komen, gebruik dan /v1/charge-plan. Dat endpoint laat uren die al voorbij zijn weg en geeft je een plan tot een deadline die je zelf opgeeft. Dat werkt net zo goed voor een vaatwasser als voor een auto: geef op wanneer het klaar moet zijn en hoeveel kWh het kost.

4. Grafiek met de prognose (ApexCharts)

Een veelgestelde vraag: hoe krijg je de voorspelling in een grafiek? Een gewone ApexCharts-kaart tekent alleen de geschiedenis van een sensor, en een prognose ligt in de toekomst. Daarvoor heb je een data_generator nodig plus een sensor die de hele reeks als attribuut heeft. De sensor Gemiddelde deze week uit onze integratie heeft dat: in het attribuut forecast staan alle 168 uren.

Let op de entity-id. In de interface heet die sensor Gemiddelde deze week, terwijl Home Assistant hem intern altijd sensor.wattwanneer_average_this_week noemt. Dat blijft zo als je Home Assistant in het Nederlands gebruikt, want entity-ids worden altijd van de Engelse naam afgeleid. Heb je de sensor zelf hernoemd, vul dan je eigen id in.

type: custom:apexcharts-card
header:
  title: Stroomprijs komende week
  show: true
graph_span: 7d
span:
  start: hour
now:
  show: true
  label: nu
series:
  - entity: sensor.wattwanneer_average_this_week
    name: Verwachte prijs
    type: area
    stroke_width: 2
    float_precision: 3
    unit: " €/kWh"
    data_generator: |
      return entity.attributes.forecast.map(p => {
        return [new Date(p.start).getTime(), p.price];
      });

Zet graph_span op 48h als je alleen vandaag en morgen wilt zien. Wil je kolommen die van kleur wisselen bij een prijsgrens, vervang dan type: area door:

    type: column
    color_threshold:
      - value: 0
        color: "#22c55e"
      - value: 0.10
        color: "#eab308"
      - value: 0.20
        color: "#ef4444"

Bouw je zonder onze integratie, dan werkt hetzelfde recept op de REST-sensor uit stap 1, mits je daar de volledige reeks als attribuut bewaart in plaats van alleen de eerstvolgende prijs.

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.

Draai je Homey Pro, dan kun je de prijzen en de voorspelling als Tags in je Flows gebruiken. Dat gaat via HomeyScript, de gratis scriptapp van Athom. Je plakt twee kant-en-klare scripts, vult je API-key in en je Flows kunnen sturen op de goedkoopste uren van de komende week.

De koppeling gebruikt drie endpoints die speciaal hiervoor zijn gemaakt:

• GET /v2/prices geeft één doorlopende prijsreeks vanaf het lopende uur, waarin gepubliceerde marktprijzen en voorspelling zijn samengevoegd, met je eigen afname- en teruglevertarief erbij.
• GET /v2/charge-plan rekent daarop een laadplan uit dat het lopende uur meeneemt.
• POST /v2/battery-plan geeft een uitvoerbaar laad-, ontlaad- en bewaarplan voor een thuisbatterij, inclusief rendement, slijtage en laadstandgrenzen.

Ze zitten in hetzelfde abonnement en hebben een eigen limiet van 20 aanvragen per minuut, los van de limiet op de v1-endpoints. Gebruik je WattWanneer in Homey én in Home Assistant op dezelfde key, dan zitten die elkaar dus niet in de weg. De volledige beschrijving staat in de v2-documentatie.

curl -H "X-API-Key: JOUW_API_KEY" \
  "https://wattwanneer.nl/api/v2/prices?from=now&hours=168"

Naar de Homey-handleiding v2-documentatie

De bestaande /v1-endpoints veranderen hier niet door. Wie die al gebruikt in Home Assistant, evcc of eigen scripts hoeft niets aan te passen.

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/charge-plan?departure=2026-08-29T07:00&energy_kwh=30&power_kw=11"

{ "energy_from_grid_kwh": 33.33,
  "energy_scheduled_kwh": 33.33,
  "completion_pct": 100.0,
  "horizon_limited": false,
  "plan": [
    { "start": "2026-08-27T10:00:00Z", "kwh": 11.0, "price_eur_per_kwh": 0.0105, "cost_eur": 0.116 },
    { "start": "2026-08-27T11:00:00Z", "kwh": 11.0, "price_eur_per_kwh": 0.0050, "cost_eur": 0.055 },
    ... ],
  "total_cost_eur": 0.35,
  "cost_if_started_now_eur": 1.90,
  "savings_eur": 1.54,
  "savings_pct": 81.5 }

curl -H "X-API-Key: JOUW_API_KEY" \
  "https://wattwanneer.nl/api/v1/charge-plan?departure=2026-08-29T07:00&energy_kwh=30&power_kw=3.7&available_from=22&available_until=6"

{ "energy_from_grid_kwh": 33.33,
  "energy_scheduled_kwh": 29.6,
  "energy_shortfall_kwh": 3.73,
  "completion_pct": 88.8,
  "note": "Er zijn te weinig beschikbare uren om de volledige vraag te laden; ..." }

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/feed-in?energy_tax=0.09161&vat=21&charges=0.021"

{ "hours": [
    { "timestamp": "2026-08-28T14:00:00Z", "market_eur_per_kwh": 0.1079,
      "feed_in_eur_per_kwh": 0.1079, "self_use_eur_per_kwh": 0.2668, "advice": "self_use" },
    { "timestamp": "2026-08-29T10:00:00Z", "market_eur_per_kwh": -0.0051,
      "feed_in_eur_per_kwh": -0.0051, "self_use_eur_per_kwh": 0.1301, "advice": "curtail" },
    ... ],
  "summary": {
    "hours_feed_in_negative": 9,
    "avg_feed_in_eur_per_kwh": 0.118,
    "avg_self_use_eur_per_kwh": 0.2791,
    "self_use_vs_feed_in_ratio": 2.4 } }

curl -H "X-API-Key: JOUW_API_KEY" \
  "https://wattwanneer.nl/api/v1/feed-in?deduction=-0.02&floor_pct=50&energy_tax=0.09161&vat=21&charges=0.021"

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

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"
  }
}