Öffentliche Beta

API Dokumentation

Die Gridweaver Energy Decision API liefert auf Basis aktueller Spotmarkt-Strompreise (aWATTar DE) eine Lade- und Entladeempfehlung für Batteriespeicher, Wallboxen, Wärmepumpen, Balkonkraftwerke, Smart-Home-Geräte, E-Auto-Flotten und Gewerbe. Eine Anfrage, eine Empfehlung — kein Cloud-Zwang, kein Vendor-Lock-in.

Quickstart

In unter 5 Minuten einsatzbereit: Konto erstellen, API Key generieren, erste Anfrage stellen.

1.Konto erstellen unter gridweaver.de/signup
2.Im Dashboard unter API Key Verwaltung einen Key erstellen und sicher speichern
3.Erste Anfrage an /api/v1/decision stellen

cURL

curl -G https://gridweaver.de/api/v1/decision \
  -H "Authorization: Bearer gw_<dein_api_key>" \
  --data-urlencode "capacity=10" \
  --data-urlencode "soc=45" \
  --data-urlencode "rate=3.7"

Authentifizierung

Alle Anfragen an /api/v1/decision und /api/v1/keys erfordern einen gültigen API Key im Authorization-Header.

HTTP Header

Authorization: Bearer gw_<dein_api_key>

Sicherheitshinweis: API Keys werden als SHA-256-Hash gespeichert und können nach der Erstellung nicht mehr im Klartext abgerufen werden. Speichere deinen Key sofort nach der Erstellung.

Endpunkte

Methode	Pfad	Auth	Beschreibung
GET	/api/v1/decision	API Key	Lade-/Entladeempfehlung berechnen
GET	/api/v1/prices	—	Aktuelle Stundenpreise abrufen
GET	/api/v1/keys	Session	API Keys auflisten
POST	/api/v1/keys	Session	Neuen API Key erstellen
DELETE	/api/v1/keys	Session	API Key widerrufen

Parameter

Query-Parameter für GET /api/v1/decision:

Parameter	Typ	Pflicht	Beschreibung	Beispiel
capacity	number	Ja	Batteriekapazität in kWh	10
soc	number	Ja	Aktueller Ladestand in % (0–100)	45
rate	number	Ja	Maximale Laderate in kW	3.7

Antwortformat

JSON

{
  "status": "success",
  "timestamp": "2026-07-09T14:00:00Z",
  "locked": false,
  "decision": {
    "action": "CHARGE_NOW",
    "confidence": 0.87,
    "until": "15:00",
    "expected_saving_eur": 0.42
  }
}

CHARGE_NOW

Jetzt laden — Preis ist günstig

DISCHARGE_NOW

Jetzt entladen — Preis ist hoch

WAIT

Abwarten — Preis im Normalbereich

Fehlerbehandlung

Status	Bedeutung
401	Ungültiger oder fehlender API Key
429	Rate Limit überschritten — max. 30 Anfragen/Minute
500	Interner Serverfehler — bitte erneut versuchen

Codebeispiele

Python

import requests

API_KEY = "gw_..."
BASE   = "https://gridweaver.de/api/v1"

resp = requests.get(
    f"{BASE}/decision",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"capacity": 10, "soc": 45, "rate": 3.7},
    timeout=10,
)
data = resp.json()
action = data["decision"]["action"]  # "CHARGE_NOW" | "DISCHARGE_NOW" | "WAIT"
print(f"Empfehlung: {action}")

Bash / Shell

Bash

#!/usr/bin/env bash
API_KEY="gw_..."
RESPONSE=$(wget -qO- \
  --header="Authorization: Bearer $API_KEY" \
  "https://gridweaver.de/api/v1/decision?capacity=10&soc=45&rate=3.7")
ACTION=$(echo "$RESPONSE" | grep -o '"action":"[^"]*"' | cut -d'"' -f4)
echo "Empfehlung: $ACTION"

Fertige Polling-Skripte für Shelly-Geräte sind im GitHub-Repository verfügbar.

Rate Limits

Die API erlaubt maximal 30 Anfragen pro Minute pro IP-Adresse. Für typische Polling-Intervalle (alle 5–15 Minuten) ist dieses Limit mehr als ausreichend. Bei Überschreitung wird HTTP 429 zurückgegeben; der Retry-After: 60-Header gibt an, wann wieder Anfragen möglich sind.