Dokumentace API

Rychlý start

Nejrychlejší způsob jak získat data — stačí jedna HTTP žádost nebo MQTT subscribe.

REST API

curl https://api.spotovky.cz/v1/today

MQTT

mosquitto_sub -h spotovky.cz -t "v1/current/json"

REST API

Base URL: https://api.spotovky.cz

Odpovědi jsou vždy ve formátu JSON s hlavičkou Content-Type: application/json. Cache je řízena hlavičkou Cache-Control: public, max-age=N kde N je počet sekund do konce aktuální 15minutové periody.

Endpointy

Formát odpovědi

Každá odpověď obsahuje datum, kurz EUR/CZK a pole slots s 15minutovými intervaly.

{
  "date": "2026-03-13",       // datum (Europe/Prague)
  "rate": 24.43,              // kurz EUR/CZK z ČNB
  "slots": [
    {
      "t":    "00:00",           // začátek intervalu
      "czk":  2.60,             // cena v Kč/kWh (zaokrouhleno na 2 des. místa)
      "rank": 55               // pořadí od nejlevnější (1 = nejlevnější)
    },
    {
      "t":    "00:15",
      "czk":  2.31,
      "rank": 52
    },
    // ... celkem 92, 96 nebo 100 slotů (viz sekce Letní/zimní čas)
  ]
}

HTTP status kódy

MQTT

Broker je dostupný na adrese spotovky.cz, port 1883. Připojení nevyžaduje uživatelské jméno ani heslo.

# mosquitto_sub
mosquitto_sub -h spotovky.cz -p 1883 -t "v1/today/json"

# Python (paho-mqtt)
import paho.mqtt.client as mqtt
client = mqtt.Client()
client.connect("spotovky.cz", 1883)
client.subscribe("v1/current/json")

Topicy

Formát zpráv today/json a tomorrow/json je shodný s odpovědí REST API. Zpráva current/json obsahuje pouze aktuální interval:

{
  "t":    "14:15",   // začátek intervalu
  "czk":  1.82,     // cena v Kč/kWh
  "rank": 12        // pořadí v rámci dnešního dne
}

Pravidla přístupu

Opakované pokusy o zakázané operace mohou vést k dočasnému zablokování IP adresy.

Harmonogram aktualizací

* Smazání retain zprávy = publish prázdné zprávy na daný topic s retain=true, standardní MQTT mechanismus.

Datové formáty

JSON formát

Podrobný popis viz sekce Formát odpovědi REST API. Zprávy na MQTT topicech today/json a tomorrow/json mají identickou strukturu.

Binární formát

Kompaktní formát pro embedded zařízení. Všechny hodnoty jsou little-endian.

today/bin a tomorrow/bin

Celková délka: 11 + N×3 bytů (283 B pro 92 period / 299 B pro 96 / 311 B pro 100).

Index slotu odpovídá pořadí od půlnoci: slot 0 = 00:00, slot 1 = 00:15, atd. Čas slotu: midnight_unix + index × 900.

current/bin

Celková délka: vždy 13 bytů.

// current/bin — 13 bytů
uint64_t timestamp;
uint16_t halere, rate_x100;
uint8_t  rank;

memcpy(&timestamp,  data + 0,  8);
memcpy(&halere,     data + 8,  2);
rank = data[10];
memcpy(&rate_x100,  data + 11, 2);

float czk     = halere    / 100.0f;
float eur_czk = rate_x100 / 100.0f;

Serial.printf("%.2f Kč/kWh, rank %d, kurz %.2f\n", czk, rank, eur_czk);

import struct, datetime, zoneinfo

def decode_day_bin(data: bytes):
    midnight, rate_x100, n = struct.unpack_from("<QHB", data, 0)
    prices = struct.unpack_from(f"<{n}H", data, 11)
    ranks  = struct.unpack_from(f"<{n}B", data, 11 + n * 2)

    eur_czk = rate_x100 / 100
    tz = zoneinfo.ZoneInfo("Europe/Prague")

    for i, (halere, rank) in enumerate(zip(prices, ranks)):
        slot_ts = midnight + i * 900
        dt = datetime.datetime.fromtimestamp(slot_ts, tz)
        czk = halere / 100
        print(f"{dt:%H:%M}  {czk:.2f} Kč/kWh  rank {rank}/{n}")

Letní a zimní čas (DST)

Počet slotů za den není vždy 96. OTE-CR publikuje skutečný počet 15minutových intervalů:

Pole slots v JSON vždy obsahuje správný počet záznamů. V binárním formátu je počet period uložen v bytu na offsetu 10 — vždy čtěte tento byte před parsováním dat.

Limity a podmínky

Dostupnost

Služba je provozována jako hobby projekt bez záruky dostupnosti. Nejsou poskytovány žádné SLA. Data mohou chybět v případě nedostupnosti OTE-CR API nebo výpadku serveru.

Zdroje dat

Spotové ceny pocházejí z OTE-CR (Operátor trhu s elektřinou). Kurz EUR/CZK pochází z ČNB (Česká národní banka) a je aktualizován jednou denně po 14:30. Pro víkendy a svátky se používá poslední dostupný kurz.

Použití

Data jsou veřejná a jejich použití není omezeno. Pokud službu využíváte ve svém projektu, oceníme zmínku o zdrojích dat (OTE-CR, spotovky.cz).

Kontakt

Dotazy, hlášení chyb nebo návrhy pište na martin@lysek.cz.