{"openapi":"3.1.0","info":{"title":"wattslot API","version":"0.1.0","description":"All-in electricity prices per 15-minute slot. Data source: Energinet (www.energidataservice.dk), CC BY 4.0; derived prices are calculated by wattslot.","license":{"name":"AGPL-3.0-only","url":"https://www.gnu.org/licenses/agpl-3.0.html"}},"components":{"schemas":{"Zone":{"type":"object","properties":{"code":{"type":"string","example":"DK2"},"currency":{"type":"string","example":"DKK"},"timeZone":{"type":"string","example":"Europe/Copenhagen"},"fullPrice":{"type":"boolean","description":"True when grid tariffs and taxes are included; false means spot price only."}},"required":["code","currency","timeZone","fullPrice"]},"GridCompany":{"type":"object","properties":{"gln":{"type":"string","example":"5790000705689"},"name":{"type":"string","example":"Radius Elnet A/S"},"zone":{"type":"string","example":"DK2"},"meteringPoints":{"type":["integer","null"],"description":"Connected consumption metering points — roughly, the number of customers."},"supported":{"type":"boolean","description":"False when the household tariff is not yet understood; prices fall back to spot."},"note":{"type":["string","null"]}},"required":["gln","name","zone","meteringPoints","supported","note"]},"PriceSlot":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"spot":{"type":"number"},"gridTariff":{"type":"number"},"tsoTariffs":{"type":"number"},"electricityTax":{"type":"number"},"supplierMarkup":{"type":"number"},"vat":{"type":"number"},"total":{"type":"number","description":"What a kWh in this slot costs, all included"}},"required":["start","end","spot","gridTariff","tsoTariffs","electricityTax","supplierMarkup","vat","total"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}},"parameters":{}},"paths":{"/v1/zones":{"get":{"summary":"Bidding zones","responses":{"200":{"description":"Every bidding zone with day-ahead prices","content":{"application/json":{"schema":{"type":"object","properties":{"zones":{"type":"array","items":{"$ref":"#/components/schemas/Zone"}}},"required":["zones"]}}}}}}},"/v1/grid-companies":{"get":{"summary":"Grid companies","parameters":[{"schema":{"type":"string","example":"DK2","description":"Only this zone"},"required":false,"description":"Only this zone","name":"zone","in":"query"}],"responses":{"200":{"description":"Danish grid companies, largest first","content":{"application/json":{"schema":{"type":"object","properties":{"gridCompanies":{"type":"array","items":{"$ref":"#/components/schemas/GridCompany"}}},"required":["gridCompanies"]}}}}}}},"/v1/status":{"get":{"summary":"Data freshness","responses":{"200":{"description":"When each dataset was last ingested, and the latest price slot per zone","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"task":{"type":"string"},"lastSuccessAt":{"type":["string","null"]},"nextAttemptAt":{"type":["string","null"]},"lastError":{"type":["string","null"]}},"required":["task","lastSuccessAt","nextAttemptAt","lastError"]}},"latestPriceSlot":{"type":"object","additionalProperties":{"type":"string"}},"degradedGridCompanies":{"type":"array","items":{"type":"object","properties":{"gln":{"type":"string"},"name":{"type":"string"},"since":{"type":"string"}},"required":["gln","name","since"]}}},"required":["tasks","latestPriceSlot","degradedGridCompanies"]}}}}}}},"/v1/prices":{"get":{"summary":"All-in price per 15-minute slot","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2}\\d?$","example":"DK2"},"required":true,"name":"zone","in":"query"},{"schema":{"type":"string","pattern":"^\\d{13}$","example":"5790000705689","description":"Grid company GLN; needed for full prices"},"required":false,"description":"Grid company GLN; needed for full prices","name":"gln","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-28","description":"Local date; defaults to today"},"required":false,"description":"Local date; defaults to today","name":"date","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":2,"default":1},"required":false,"name":"days","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"maximum":10,"default":0,"description":"Your supplier's markup per kWh, excluding VAT"},"required":false,"description":"Your supplier's markup per kWh, excluding VAT","name":"markup","in":"query"}],"responses":{"200":{"description":"Prices with a per-component breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"currency":{"type":"string"},"unit":{"type":"string"},"gridCompany":{"type":["object","null"],"properties":{"gln":{"type":"string"},"name":{"type":"string"}},"required":["gln","name"]},"mode":{"type":"string","enum":["full","spot-only"]},"note":{"type":["string","null"],"description":"Why prices are spot-only, if they are"},"from":{"type":"string"},"to":{"type":"string"},"complete":{"type":"boolean","description":"False until every slot is published"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/PriceSlot"}}},"required":["zone","currency","unit","gridCompany","mode","note","from","to","complete","slots"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown zone or grid company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/co2":{"get":{"summary":"CO₂ intensity per 15-minute slot","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2}\\d?$","example":"DK2"},"required":true,"name":"zone","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-28","description":"Local date; defaults to today"},"required":false,"description":"Local date; defaults to today","name":"date","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":2,"default":1},"required":false,"name":"days","in":"query"}],"responses":{"200":{"description":"Forecast and measured grid CO₂ intensity (g/kWh), averaged per 15 minutes","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"unit":{"type":"string","enum":["g/kWh"]},"slots":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"forecast":{"type":["number","null"]},"actual":{"type":["number","null"]}},"required":["start","forecast","actual"]}}},"required":["zone","unit","slots"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown zone or grid company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cheapest":{"get":{"summary":"Cheapest time to use electricity","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2}\\d?$","example":"DK2"},"required":true,"name":"zone","in":"query"},{"schema":{"type":"string","pattern":"^\\d{13}$","example":"5790000705689","description":"Grid company GLN; needed for full prices"},"required":false,"description":"Grid company GLN; needed for full prices","name":"gln","in":"query"},{"schema":{"type":"number","minimum":0.25,"maximum":24,"example":2},"required":true,"name":"hours","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Defaults to now"},"required":false,"description":"Defaults to now","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Defaults to 48 hours after `from`"},"required":false,"description":"Defaults to 48 hours after `from`","name":"to","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"false lets the load pause, e.g. EV charging"},"required":false,"description":"false lets the load pause, e.g. EV charging","name":"contiguous","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"maximum":10,"default":0,"description":"Your supplier's markup per kWh, excluding VAT"},"required":false,"description":"Your supplier's markup per kWh, excluding VAT","name":"markup","in":"query"}],"responses":{"200":{"description":"The cheapest slots, compared with starting now","content":{"application/json":{"schema":{"type":"object","properties":{"zone":{"type":"string"},"currency":{"type":"string"},"unit":{"type":"string"},"gridCompany":{"type":["object","null"],"properties":{"gln":{"type":"string"},"name":{"type":"string"}},"required":["gln","name"]},"mode":{"type":"string","enum":["full","spot-only"]},"note":{"type":["string","null"],"description":"Why prices are spot-only, if they are"},"hours":{"type":"number"},"contiguous":{"type":"boolean"},"cheapest":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"},"averagePrice":{"type":"number"},"slots":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"total":{"type":"number"}},"required":["start","total"]}}},"required":["start","end","averagePrice","slots"]},"startNow":{"type":["object","null"],"properties":{"averagePrice":{"type":"number"}},"required":["averagePrice"],"description":"The same energy used from `from` onwards, for comparison"},"message":{"type":["string","null"]}},"required":["zone","currency","unit","gridCompany","mode","note","hours","contiguous","cheapest","startNow","message"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown zone or grid company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}