API v1

WattBox API

Integrujte naše kalkulačky elektromobilů na váš web. Výpočty nákladů, dojezdu a nabíjení dostupné přes REST API nebo embed widget.

1 Rychlý start

Získejte API klíč

Napište nám na wattbox.api@noah.fit 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 API Endpointy

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-350	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`.

Jak funguje nabíjecí křivka: Pro DC nabíjení (>22 kW) API modeluje realistickou křivku podle dat Škoda Enyaq 85. Výkon klesá s rostoucím SoC - např. při 80% SoC nabíjí jen ~50% maximálního výkonu. AC nabíjení (≤22 kW) používá konstantní výkon.

Příklad requestu

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

// 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" (≤22kW) nebo "DC" (>22kW)
`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 }
    ]
  }
}

4 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`	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`)

5 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

6 Error kódy

HTTP Status	Kód	Popis
`401`	`UNAUTHORIZED`	Chybí nebo neplatný API klíč
`400`	`VALIDATION_ERROR`	Neplatné vstupní parametry
`400`	`INVALID_JSON`	Neplatný JSON v těle requestu
`405`	`METHOD_NOT_ALLOWED`	Endpoint podporuje pouze POST
`500`	`CALCULATION_ERROR`	Interní chyba při výpočtu

Potřebujete API klíč?

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

wattbox.api@noah.fit