API v1

WattBox API

Data nabíjecích stanic a kalkulačky elektromobilů přes REST API. Mapa s 2 500+ stanicemi, výpočty nákladů, dojezdu, nabíjení, degradace baterie a srovnání tarifů.

Mapa stanic Kalkulačky Embed Widget Scriptable Widget

1 Rychlý start

Získejte API klíč

Napište nám na info@wattbox.cz s popisem vašeho projektu.

Vyberte metodu integrace

REST API pro vlastní UI, nebo Embed Widget pro rychlé vložení.

Integrujte

Použijte příklady níže pro vaši platformu.

2 Autentizace

Všechny API requesty vyžadují API klíč v Authorization headeru:

Authorization: Bearer YOUR_API_KEY

3 Mapa nabíjecích stanic

Data 2 500+ nabíjecích stanic v ČR. GPS souřadnice, konektory, výkony, operátoři, vybavenost okolí a hodnocení uživatelů.

GET /api/stations

Seznam všech nabíjecích stanic s kompletními detaily. Filtrovatelný podle výkonu a operátora.

Parametry a response

Query parametry (volitelné)

Parametr	Typ	Popis
`power`	number	Minimální výkon v kW (např. `?power=50` vrátí jen DC a rychlonabíječky)
`operator`	string	Filtr podle operátora (např. `?operator=cez`)

Response — pole stanic

Pole	Typ	Popis
`id`	number	Unikátní ID stanice
`name`	string	Název stanice
`display_name`	string?	Vlastní zobrazovaný název (pokud existuje)
`operator`	string	Název operátora
`operator_key`	string	Klíč operátora (cez, eon, orlen...)
`address_line`	string	Adresa
`city`	string	Město
`latitude`	number	GPS šířka
`longitude`	number	GPS délka
`max_power_kw`	number	Maximální výkon v kW
`is_fast_charging`	boolean	DC rychlonabíjení (>22 kW)
`connectors`	array	Konektory — typ, výkon, počet
`amenities`	object	Vybavenost okolí (WC, restaurace, supermarket...)
`avg_rating`	number	Průměrné hodnocení (0–5)
`review_count`	number	Počet recenzí
`status`	string	operational, planned, out_of_service, removed

Příklad requestu

curl https://wattbox.cz/api/stations \
  -H "Authorization: Bearer YOUR_API_KEY"

# Jen rychlonabíječky nad 50 kW
curl "https://wattbox.cz/api/stations?power=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Příklad response (zkráceno)

{
  "success": true,
  "count": 2512,
  "stations": [
    {
      "id": 1,
      "name": "Chebská 2931, Aš",
      "operator": "E.ON",
      "operator_key": "eon",
      "city": "Aš",
      "latitude": 50.2138,
      "longitude": 12.2019,
      "max_power_kw": 50,
      "is_fast_charging": true,
      "connectors": [
        { "type_name": "CCS", "power_kw": 50, "quantity": 1 },
        { "type_name": "CHAdeMO", "power_kw": 50, "quantity": 1 }
      ],
      "amenities": { "supermarket": 150, "restaurant": 200 },
      "avg_rating": 4.2,
      "review_count": 3,
      "status": "operational"
    }
  ]
}

GET /api/stations/:id

Detail jedné stanice podle ID. Vrací kompletní data včetně všech konektorů a provozní doby.

Parametry a response

URL parametry

Parametr	Typ	Popis
`id`	number	ID stanice (z endpointu `/api/stations`)

Příklad

curl https://wattbox.cz/api/stations/42 \
  -H "Authorization: Bearer YOUR_API_KEY"

4 Kalkulačky

Výpočty nákladů, dojezdu, nabíjení, degradace baterie, TCO a srovnání tarifů. Všechny endpointy vyžadují POST s JSON body.

POST /api/v1/calculate/costs

Výpočet měsíčních a ročních nákladů na elektřinu s volitelným srovnáním s palivovým autem.

Request parametry

Povinné parametry

Parametr	Typ	Rozsah	Popis
`consumption`	number	10-35	Spotřeba elektromobilu v kWh/100km (WLTP nebo reálná - viz info níže)
`distance`	number	100-10000	Měsíční nájezd v km
`electricPrice`	number	>0	Cena elektřiny za kWh
`currency`	string	CZK, EUR	Měna pro výstupní hodnoty

WLTP vs reálná spotřeba: Parametr consumption může být WLTP hodnota z katalogu (např. 17 kWh/100km) nebo vaše reálná naměřená spotřeba (např. 20 kWh/100km).

WLTP + teplotní korekce: Zadejte WLTP hodnotu a month - API automaticky navýší spotřebu podle teploty (v zimě až +28%).
Reálná spotřeba: Zadejte vaši naměřenou spotřebu bez month - API ji použije přímo bez úprav.

Volitelné: Teplotní korekce

Parametr	Typ	Popis
`month`	number	Měsíc 0-11 (leden=0). Aktivuje teplotní korekci spotřeby podle průměrných teplot v ČR. Použijte s WLTP spotřebou.

Volitelné: Srovnání s palivem

Pokud chcete srovnání s palivovým autem, musíte zadat všechny tři parametry níže.

Parametr	Typ	Hodnoty	Popis
`fuelType`	string	petrol, diesel, lpg	Typ paliva
`fuelConsumption`	number	>0	Spotřeba paliva v l/100km
`fuelPrice`	number	>0	Cena paliva za litr

Příklad requestu

// Základní výpočet (jen elektřina)
{ "consumption": 18, "distance": 1500, "electricPrice": 5.5, "currency": "CZK" }

// S teplotní korekcí (leden)
{ "consumption": 18, "distance": 1500, "electricPrice": 5.5, "currency": "CZK", "month": 0 }

// Se srovnáním s benzínem
{
  "consumption": 18, "distance": 1500, "electricPrice": 5.5, "currency": "CZK",
  "month": 0,
  "fuelType": "petrol", "fuelConsumption": 7, "fuelPrice": 38
}

Response

Pole	Typ	Popis
monthly
`electricCost`	number	Měsíční náklady na elektřinu
`electricKwh`	number	Měsíční spotřeba v kWh
`fuelCost`	number?	Měsíční náklady na palivo (pokud srovnání)
`fuelLiters`	number?	Měsíční spotřeba paliva v litrech
`savings`	number?	Měsíční úspora oproti palivu
yearly
`electricCost`	number	Roční náklady na elektřinu
`electricKwh`	number	Roční spotřeba v kWh
`fuelCost`	number?	Roční náklady na palivo
`savings`	number?	Roční úspora oproti palivu
`co2Savings`	number?	Roční úspora CO2 v tunách
perKm
`electric`	number	Cena za km na elektřinu
`fuel`	number?	Cena za km na palivo
faktory (pokud použita teplotní korekce)
`temperatureFactor`	number?	Aplikovaný teplotní faktor EV (např. 1.28 = +28% spotřeba)
`fuelTemperatureFactor`	number?	Teplotní faktor paliva

Příklad response

{
  "success": true,
  "data": {
    "monthly": { "electricCost": 1485, "electricKwh": 270, "fuelCost": 3990, "savings": 2505 },
    "yearly": { "electricCost": 17820, "fuelCost": 47880, "savings": 30060, "co2Savings": 2.42 },
    "perKm": { "electric": 0.99, "fuel": 2.66 },
    "temperatureFactor": 1.28
  },
  "meta": { "timestamp": "2026-01-15T10:30:00Z", "currency": "CZK" }
}

POST /api/v1/calculate/range

Výpočet reálného dojezdu s vlivem teploty, zatížení a střešního boxu.

Request parametry

Povinné parametry

Parametr	Typ	Rozsah	Popis
`battery`	number	20-120	Kapacita baterie v kWh
`soc`	number	0-100	Aktuální stav nabití v % (State of Charge)
`consumption`	number	10-35	Spotřeba v kWh/100km (doporučujeme WLTP)
`month`	number	0-11	Měsíc (leden=0). Určuje teplotu pro výpočet.

Jak funguje výpočet: API vždy aplikuje teplotní a zátěžové faktory na zadanou spotřebu.

wltpRange = dojezd vypočtený ze zadané spotřeby bez faktorů (ideální podmínky)
realRange = dojezd po aplikaci teplotního faktoru a zatížení (realistický odhad)
adjustedConsumption = spotřeba navýšená o faktory (např. 18 × 1.28 = 23 kWh/100km v zimě)

Volitelné parametry

Parametr	Typ	Default	Popis
`load`	number	0	Zatížení: 0 = bez, 10 = plně naloženo (+10% spotřeba)
`roof`	boolean	false	Střešní box (+15% spotřeba kvůli aerodynamice)

Příklad requestu

{ "battery": 77, "soc": 80, "consumption": 18, "month": 0 }

// S plným zatížením a střešním boxem
{ "battery": 77, "soc": 80, "consumption": 18, "month": 0, "load": 10, "roof": true }

Response

Pole	Typ	Popis
`realRange`	number	Reálný dojezd v km (po aplikaci všech faktorů)
`wltpRange`	number	Teoretický WLTP dojezd v km (bez faktorů)
`difference`	number	Rozdíl v km (realRange - wltpRange)
`differencePercent`	number	Rozdíl v procentech
`usableCapacity`	number	Použitelná kapacita v kWh (95% baterie × SoC)
`adjustedConsumption`	number	Upravená spotřeba v kWh/100km (po faktorech)
`temperatureFactor`	number	Teplotní faktor (např. 1.28 = +28% spotřeba v zimě)
`loadFactor`	number	Faktor zatížení (1.0 = žádné, 1.25 = plné + střešní box)
`temperature`	number	Průměrná teplota pro daný měsíc v °C

Příklad response

{
  "success": true,
  "data": {
    "realRange": 268,
    "wltpRange": 342,
    "difference": -74,
    "differencePercent": -21.6,
    "usableCapacity": 58.5,
    "adjustedConsumption": 23.0,
    "temperatureFactor": 1.28,
    "loadFactor": 1.0,
    "temperature": -1
  }
}

POST /api/v1/calculate/charging

Výpočet času a ceny nabíjení s realistickou DC nabíjecí křivkou.

Request parametry

Povinné parametry

Parametr	Typ	Rozsah	Popis
`battery`	number	20-120	Kapacita baterie v kWh
`socStart`	number	0-95	Počáteční stav nabití v %
`socEnd`	number	5-100	Cílový stav nabití v %
`power`	number	2-400	Maximální výkon nabíječky v kW
`price`	number	>0	Cena elektřiny za kWh
`currency`	string	CZK, EUR	Měna

Volitelné parametry

Parametr	Typ	Popis
`consumption`	number	Spotřeba v kWh/100km. Pokud zadáno, response obsahuje `rangeGained`.
`chargingProfile`	string	Nabíjecí profil vozidla. Ovlivňuje tvar DC nabíjecí křivky. Viz tabulka níže. Default: `meb`.

Jak funguje nabíjecí křivka: Pro DC nabíjení (≥50 kW) API modeluje realistickou křivku podle zvoleného nabíjecího profilu. Výkon klesá s rostoucím SoC - např. při 80% SoC nabíjí jen ~50% maximálního výkonu. AC nabíjení (<50 kW) používá konstantní výkon.

Dostupné nabíjecí profily (chargingProfile):

meb — MEB platforma, nižší DC výkon (Enyaq 85 RWD, Elroq 60, ID.3/ID.4)
meb_fast — MEB platforma, vyšší DC výkon 175+ kW (Enyaq 85x/RS, Elroq 85/RS, ID.4 GTX, ID.7, ID.Buzz)
800v — 800V architektura (Hyundai Ioniq 5, Kia EV6, Mercedes CLA)
tesla — Tesla (Model 3 Highland, Model Y Juniper)
budget — Budget / starší EV (Dacia Spring, MG4, Hyundai Kona, Kia EV3, Volvo EX30)

Příklad requestu

// DC rychlonabíjení 20→80% (Enyaq 85, MEB profil)
{ "battery": 77, "socStart": 20, "socEnd": 80, "power": 150, "price": 8, "currency": "CZK" }

// DC rychlonabíjení Ioniq 5 (800V profil)
{ "battery": 84, "socStart": 10, "socEnd": 80, "power": 240, "price": 8, "currency": "CZK", "chargingProfile": "800v" }

// AC domácí nabíjení přes noc s výpočtem dojezdu
{ "battery": 77, "socStart": 20, "socEnd": 100, "power": 11, "price": 4.5, "currency": "CZK", "consumption": 18 }

Response

Pole	Typ	Popis
time
`hours`	number	Celé hodiny
`minutes`	number	Zbývající minuty
`totalMinutes`	number	Celkový čas v minutách
ostatní
`energy`	number	Nabité kWh
`cost`	number	Cena nabíjení
`rangeGained`	number?	Získaný dojezd v km (pokud zadána spotřeba)
`chargingType`	string	"AC" (<50kW) nebo "DC" (≥50kW)
`curve`	array	Nabíjecí křivka (jen DC) - body s SoC, výkonem a časem

Příklad response

{
  "success": true,
  "data": {
    "time": { "hours": 0, "minutes": 32, "totalMinutes": 32 },
    "energy": 46.2,
    "cost": 370,
    "rangeGained": 257,
    "chargingType": "DC",
    "curve": [
      { "soc": 20, "power": 144, "cumulativeTime": 0 },
      { "soc": 40, "power": 138, "cumulativeTime": 8.5 },
      { "soc": 60, "power": 105, "cumulativeTime": 17.2 },
      { "soc": 80, "power": 72, "cumulativeTime": 32 }
    ]
  }
}

POST /api/v1/calculate/degradation

Odhad stavu baterie (SoH) podle stáří, nájezdu a stylu nabíjení. Založeno na datech Geotab 2025.

Request parametry

Povinné parametry

Parametr	Typ	Rozsah	Popis
`batterySize`	number	20-120	Kapacita baterie v kWh
`vehicleAge`	number	0-15	Stáří vozidla v letech
`currentMileage`	number	0-500000	Aktuální nájezd v km
`annualMileage`	number	1000-100000	Roční nájezd v km (pro predikce)
`dcPercent`	number	0-100	Procento DC (rychlo)nabíjení
`batteryType`	string	nmc, lfp	Typ chemie baterie

Typy baterií:

NMC - většina elektromobilů (VW, Škoda, BMW, Mercedes, Hyundai...)
LFP - Tesla Standard Range, BYD, některé čínské vozy. Delší životnost (~15% pomalejší degradace).

Volitelné parametry

Parametr	Typ	Default	Popis
`warrantyYears`	number	8	Záruční doba v letech
`warrantyKm`	number	160000	Záruční nájezd v km

Příklad requestu

// Škoda Enyaq 85 (NMC), 3 roky, 60 000 km
{
  "batterySize": 77,
  "vehicleAge": 3,
  "currentMileage": 60000,
  "annualMileage": 20000,
  "dcPercent": 20,
  "batteryType": "nmc"
}

// Tesla Model 3 SR (LFP), 2 roky, 40 000 km
{
  "batterySize": 60,
  "vehicleAge": 2,
  "currentMileage": 40000,
  "annualMileage": 20000,
  "dcPercent": 30,
  "batteryType": "lfp"
}

Response

Pole	Typ	Popis
`soh`	number	Aktuální State of Health v % (70-100)
`remainingCapacity`	number	Zbývající kapacita v kWh
`lostCapacity`	number	Ztracená kapacita v kWh
predictions
`years2`	number	Predikce SoH za 2 roky
`years5`	number	Predikce SoH za 5 let
`years8`	number	Predikce SoH za 8 let
záruka
`isInWarranty`	boolean	Je baterie v záruce?
`warrantyStatus`	string	"ok", "warning" (blíží se limitu), "expired"
`warrantyRemainingYears`	number	Zbývající roky záruky
`warrantyRemainingKm`	number	Zbývající km záruky

Příklad response

{
  "success": true,
  "data": {
    "soh": 94.2,
    "remainingCapacity": 72.5,
    "lostCapacity": 4.5,
    "predictions": {
      "years2": 91.8,
      "years5": 87.3,
      "years8": 83.1
    },
    "isInWarranty": true,
    "warrantyStatus": "ok",
    "warrantyRemainingYears": 5,
    "warrantyRemainingKm": 100000
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00Z",
    "sourceUrl": "https://wattbox.cz/kalkulacka/degradace?bat=77&age=3&km=60000&annual=20000&dc=20&type=nmc"
  }
}

POST /api/v1/calculate/tco

Srovnání celkových nákladů vlastnictví (TCO) elektromobilu vs spalovacího vozu za X let.

Request parametry

Povinné parametry

Parametr	Typ	Rozsah	Popis
`evPrice`	number	300000-3000000	Pořizovací cena elektromobilu
`combustionPrice`	number	200000-2000000	Pořizovací cena spalovacího vozu
`annualMileage`	number	5000-50000	Roční nájezd v km
`years`	number	1-15	Doba srovnání v letech
`evConsumption`	number	10-35	Spotřeba EV v kWh/100km
`electricityPrice`	number	>0	Cena elektřiny za kWh
`fuelConsumption`	number	4-15	Spotřeba paliva v l/100km
`fuelPrice`	number	>0	Cena paliva za litr
`currency`	string	CZK, EUR	Měna (volitelné, default: CZK)

Volitelné parametry

Parametr	Typ	Default	Popis
`evMaintenance`	number	4000	Roční servis EV
`combustionMaintenance`	number	8000	Roční servis spalovacího
`evInsurance`	number	18000	Roční pojištění EV
`combustionInsurance`	number	15000	Roční pojištění spalovacího
`evSubsidy`	number	0	Dotace na EV
`evResidualPercent`	number	45	Zůstatková hodnota EV v %
`combustionResidualPercent`	number	55	Zůstatková hodnota spalovacího v %

TCO výpočet zahrnuje:

Pořizovací náklady - cena vozu mínus zůstatková hodnota a dotace
Palivo/elektřina - podle spotřeby a ročního nájezdu
Servis a údržba - EV má nižší náklady (méně pohyblivých dílů)
Pojištění - EV bývá dražší kvůli vyšší pořizovací ceně

Příklad requestu

// Srovnání Škoda Enyaq vs Octavia za 5 let
{
  "evPrice": 1100000,
  "combustionPrice": 750000,
  "annualMileage": 15000,
  "years": 5,
  "evConsumption": 18,
  "electricityPrice": 5.5,
  "fuelConsumption": 7,
  "fuelPrice": 38,
  "currency": "CZK",
  "evResidualPercent": 60,
  "combustionResidualPercent": 45
}

Response

Pole	Typ	Popis
`evTotalCost`	number	Celkové náklady na EV
`combustionTotalCost`	number	Celkové náklady na spalovací
`difference`	number	Rozdíl (+ = EV dražší, - = EV levnější)
`evIsWinner`	boolean	Je EV výhodnější?
`breakEvenYear`	number?	Rok, kdy se EV vyplatí (null = nikdy)
`annualFuelSavings`	number	Roční úspora na palivu
`evCostPerKm`	number	Náklady na km u EV
`combustionCostPerKm`	number	Náklady na km u spalovacího
evBreakdown (rozklad nákladů EV)
`purchase`	number	Čisté pořizovací náklady (po odečtu zůstatkové hodnoty a dotace)
`fuel`	number	Náklady na elektřinu za celou dobu
`maintenance`	number	Servisní náklady
`insurance`	number	Náklady na pojištění
`total`	number	Celkové náklady
combustionBreakdown (rozklad nákladů spalovacího)
`purchase`	number	Čisté pořizovací náklady (po odečtu zůstatkové hodnoty)
`fuel`	number	Náklady na palivo za celou dobu
`maintenance`	number	Servisní náklady
`insurance`	number	Náklady na pojištění
`total`	number	Celkové náklady
yearlyBreakdown
`year`	number	Rok (0 = pořízení, 1-N = provoz)
`evCumulative`	number	Kumulativní náklady EV
`combustionCumulative`	number	Kumulativní náklady spalovacího

Příklad response

{
  "success": true,
  "data": {
    "evTotalCost": 710750,
    "combustionTotalCost": 862500,
    "difference": -151750,
    "evIsWinner": true,
    "breakEvenYear": 4,
    "annualFuelSavings": 25050,
    "evCostPerKm": 4.74,
    "combustionCostPerKm": 5.75,
    "evBreakdown": {
      "purchase": 440000,
      "fuel": 74250,
      "maintenance": 15000,
      "insurance": 90000,
      "total": 619250
    },
    "combustionBreakdown": {
      "purchase": 412500,
      "fuel": 199500,
      "maintenance": 60000,
      "insurance": 75000,
      "total": 747000
    },
    "yearlyBreakdown": [
      { "year": 0, "evCumulative": 440000, "combustionCumulative": 412500 },
      { "year": 1, "evCumulative": 494150, "combustionCumulative": 502500 },
      { "year": 2, "evCumulative": 548300, "combustionCumulative": 592500 },
      { "year": 3, "evCumulative": 602450, "combustionCumulative": 682500 },
      { "year": 4, "evCumulative": 656600, "combustionCumulative": 772500 },
      { "year": 5, "evCumulative": 710750, "combustionCumulative": 862500 }
    ]
  },
  "meta": { "timestamp": "2026-01-28T12:00:00Z", "currency": "CZK" }
}

POST /api/v1/calculate/tariffs

Srovnání domácích elektrotarifů a veřejných nabíjecích karet. Najde nejlevnější kombinaci tarifu + karty pro vaše nabíjecí zvyky.

Request parametry

Povinné parametry

Parametr	Typ	Rozsah	Popis
`consumption`	number	5-40	Spotřeba elektromobilu v kWh/100km
`annualMileage`	number	1000-100000	Roční nájezd v km
`homeChargingPercent`	number	0-100	Podíl nabíjení doma v %
`publicAcPercent`	number	0-100	Podíl AC veřejného nabíjení v %
`publicDcPercent`	number	0-100	Podíl DC veřejného nabíjení v %
`publicUfcPercent`	number	0-100	Podíl UFC veřejného nabíjení v %
`currency`	string	CZK, EUR	Měna

Rozložení veřejného nabíjení: publicAcPercent + publicDcPercent + publicUfcPercent musí dát dohromady 100 %.

AC = do 22 kW (pomalé nabíjení, např. ve městě)
DC = 22–149 kW (běžné rychlonabíječky)
UFC = 150+ kW (ultra-rychlé nabíjení, dálnice)

Volitelné: Vlastní tarif

Parametr	Typ	Popis
`customTariff.priceVt`	number	Cena vysokého tarifu v Kč/kWh
`customTariff.priceNt`	number?	Cena nízkého tarifu v Kč/kWh (null = jednotarif)
`customTariff.ntChargingRatio`	number	Podíl nabíjení v NT (0–1, např. 0.85 pro D27d)
`customTariff.label`	string	Název vlastního tarifu (max 30 znaků)

Příklad requestu

// Základní srovnání — 9 domácích tarifů × 12+ nabíjecích karet
{
  "consumption": 17,
  "annualMileage": 15000,
  "homeChargingPercent": 70,
  "publicAcPercent": 20,
  "publicDcPercent": 60,
  "publicUfcPercent": 20,
  "currency": "CZK"
}

// S vlastním tarifem (např. MND dvoutarif)
{
  "consumption": 17,
  "annualMileage": 15000,
  "homeChargingPercent": 70,
  "publicAcPercent": 20,
  "publicDcPercent": 60,
  "publicUfcPercent": 20,
  "currency": "CZK",
  "customTariff": {
    "priceVt": 5.50,
    "priceNt": 3.80,
    "ntChargingRatio": 0.85,
    "label": "MND Elektřina"
  }
}

Response

Pole	Typ	Popis
bestOverall (nejlevnější kombinace)
`homeTariff`	object	Domácí tarif (label, tariff, provider, priceVt, priceNt)
`publicCard`	object	Nabíjecí karta (name, operatorKey, priceAc/Dc/Ufc, monthlyFee)
`totalAnnualCost`	number	Celkové roční náklady v Kč
`homeAnnualCost`	number	Roční náklady na domácí nabíjení
`publicAnnualCost`	number	Roční náklady na veřejné nabíjení (vč. poplatků)
`effectiveTotalPrice`	number	Efektivní cena za kWh
`isCustom`	boolean	Jedná se o vlastní tarif?
statistiky
`totalAnnualKwh`	number	Celková roční spotřeba v kWh
`homeKwh`	number	Spotřeba doma v kWh
`publicKwh`	number	Spotřeba veřejně v kWh
`savingsVsWorst`	number	Úspora oproti nejdražší kombinaci
combinations (top 20)
`totalCombinations`	number	Celkový počet kombinací
`combinations`	array	Top 20 kombinací seřazených od nejlevnější

Příklad response (zkráceno)

{
  "success": true,
  "data": {
    "bestOverall": {
      "homeTariff": { "label": "ČEZ D27d", "tariff": "D27d", "provider": "cez" },
      "publicCard": { "name": "AC/DC", "operatorKey": "polyfazer" },
      "totalAnnualCost": 12850,
      "homeAnnualCost": 8470,
      "publicAnnualCost": 4380,
      "effectiveTotalPrice": 4.52,
      "isCustom": false
    },
    "totalAnnualKwh": 2550,
    "homeKwh": 1785,
    "publicKwh": 765,
    "savingsVsWorst": 8200,
    "totalCombinations": 108,
    "combinations": [ ... ]
  },
  "meta": {
    "timestamp": "2026-02-11T12:00:00Z",
    "currency": "CZK",
    "sourceUrl": "https://wattbox.cz/kalkulacka/tarify?cons=17&km=15000&home=70&ac=20&dc=60&ufc=20"
  }
}

5 Embed Widget

Nejjednodušší způsob integrace. Stačí vložit tento kód na vaši stránku:

<!-- WattBox Calculator Widget -->
<div id="wattbox-calculator"></div>
<script
  src="https://wattbox.cz/embed/widget.js"
  data-type="costs"
  data-theme="light"
  data-currency="CZK">
</script>

Parametry widgetu

Parametr	Hodnoty	Popis
`data-type`	`costs`, `range`, `charging`, `degradation`, `tco`, `tarify`	Typ kalkulačky
`data-theme`	`light`, `dark`	Barevné téma
`data-currency`	`CZK`, `EUR`	Výchozí měna (default: CZK)
`data-container`	ID elementu	Vlastní ID kontejneru (default: `wattbox-calculator`)

CORS

API i embed widgety podporují cross-origin requesty. Všechny API endpointy vrací Access-Control-Allow-Origin: * header, takže je můžete volat z libovolné domény.

Pro embed widgety doporučujeme použít widget.js (viz výše), který automaticky vytvoří iframe s korektní komunikací.

Scriptable Widget

Widget pro iPhone home screen zobrazující nejbližší nabíjecí stanice s real-time dostupností. Vyžaduje aplikaci Scriptable.

GET /api/v1/widget/nearby public

Nejbližší nabíjecí stanice s EVSE dostupností. Veřejný endpoint bez API klíče.

Parametry a response

Query parametry

Parametr	Typ	Default	Popis
`lat`	number	povinný	GPS šířka
`lng`	number	povinný	GPS délka
`radius`	number	15	Max vzdálenost v km (1-50)
`limit`	number	5	Max počet stanic (1-10)
`power`	number	0	Min výkon nabíječky v kW

Příklad requestu

curl "https://wattbox.cz/api/v1/widget/nearby?lat=50.08&lng=14.44"

# Jen DC nabíječky do 10 km
curl "https://wattbox.cz/api/v1/widget/nearby?lat=50.08&lng=14.44&radius=10&power=50"

Příklad response

{
  "success": true,
  "stations": [
    {
      "id": 123,
      "name": "ČEZ Praha Anděl",
      "city": "Praha",
      "operatorName": "ČEZ",
      "operatorColor": "#F37A1F",
      "distance_km": 1.2,
      "max_power_kw": 150,
      "is_fast": true,
      "evse": {
        "available": 2,
        "total": 4,
        "has_data": true,
        "last_updated": "2026-02-22T14:30:00Z"
      }
    }
  ]
}

Instalace widgetu

Nainstalujte Scriptable

Stáhněte zdarma z App Store.

Stáhněte skript

Otevřete wattbox-nearby.js v Safari na iPhonu a zkopírujte obsah do nového skriptu v Scriptable.

Přidejte widget na home screen

Dlouze podržte na home screen → + → Scriptable → vyberte velikost (medium doporučujeme) → vyberte skript „wattbox-nearby".

Konfigurace

Na začátku skriptu upravte CONFIG podle svých preferencí:

const CONFIG = {
  RADIUS_KM: 15,   // Max vzdálenost stanic v km (1-50)
  MIN_POWER: 0,    // Min výkon nabíječky v kW (0 = všechny, 50 = jen DC)
  LIMIT: 5,        // Max počet stanic (1-10)
};

Podporované velikosti

Small — 1 nejbližší stanice
Medium — 3 nejbližší stanice

Funkce

Auto dark/light mode, offline cache, tap otevře mapu na wattbox.cz

6 Příklady kódu

curl -X POST https://wattbox.cz/api/v1/calculate/costs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consumption": 18,
    "distance": 1500,
    "electricPrice": 5.5,
    "currency": "CZK"
  }'

const response = await fetch('https://wattbox.cz/api/v1/calculate/costs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    consumption: 18,
    distance: 1500,
    electricPrice: 5.5,
    currency: 'CZK',
  }),
});

const data = await response.json();
console.log(data.data.monthly.electricCost); // 1485

import requests

response = requests.post(
    'https://wattbox.cz/api/v1/calculate/costs',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'consumption': 18,
        'distance': 1500,
        'electricPrice': 5.5,
        'currency': 'CZK',
    }
)

data = response.json()
print(data['data']['monthly']['electricCost'])  # 1485

7 Chybové odpovědi

Všechny chybové odpovědi mají jednotný JSON formát. HTTP status kód odpovídá typu chyby.

Formát chybové odpovědi

{
  "success": false,
  "error": "Popis chyby",
  "code": "ERROR_CODE"
}

Autentizace a autorizace

Status	Kód	Kdy nastane	Řešení
`401`	`UNAUTHORIZED`	Chybí nebo neplatný API klíč	Zkontrolujte `Authorization: Bearer` header

Chyby requestu

Status	Kód	Kdy nastane	Řešení
`400`	`VALIDATION_ERROR`	Neplatné vstupní parametry	Zkontrolujte typy a rozsahy parametrů
`400`	`INVALID_JSON`	Nevalidní JSON v body	Ověřte JSON syntax a `Content-Type: application/json`
`405`	`METHOD_NOT_ALLOWED`	Špatná HTTP metoda	Kalkulačky vyžadují POST, stanice GET

Serverové chyby

Status	Kód	Kdy nastane	Řešení
`500`	`CALCULATION_ERROR`	Chyba při výpočtu	Zkuste request opakovat, pokud přetrvává kontaktujte nás

Příklad validační chyby (400)

{
  "success": false,
  "error": "Neplatné vstupní parametry",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "field": "consumption", "message": "Hodnota musí být mezi 10 a 35" },
    { "field": "currency", "message": "Povolené hodnoty: CZK, EUR" }
  ]
}

Potřebujete API klíč?

Napište nám s popisem vašeho projektu a my vám rádi pomůžeme s integrací.

info@wattbox.cz