eMeteo API v3

Rýchly štart

Základná cesta je https://emeteo.sk/api/v3. Všetky dátové endpointy používajú metódu GET, vracajú JSON a vyžadujú API kľúč.

curl --request GET \
  --url "https://emeteo.sk/api/v3/stations?per_page=10" \
  --header "Accept: application/json" \
  --header "X-API-Key: em3_VAS_KLUC"

Autentifikácia

Kľúč posielajte v HTTP hlavičke. Odporúčaný je X-API-Key; podporovaný je aj Bearer token.

X-API-Key: em3_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# alebo
Authorization: Bearer em3_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Neposielajte obe hlavičky naraz. Kľúč uchovávajte na strane servera alebo v správcovi tajomstiev, nepridávajte ho do URL, verejného JavaScriptu, mobilného balíka ani repozitára a všetky požiadavky posielajte cez HTTPS.

Kľúč môže mať obmedzené endpointy, stanice, IP adresy, povolené webové originy, počet volaní a rozsah historických údajov.

Formát odpovede

Každá odpoveď má rovnaký obal. generated_at je UNIX timestamp v sekundách. Hodnota request_id sa nachádza aj v hlavičke X-Request-ID; uveďte ju pri nahlasovaní problému.

{
  "data": { ... },
  "meta": {
    "request_id": "c192f20fd7c1423f89e6c7b43aa1d86e",
    "api_version": "3.0",
    "generated_at": 1790344800
  },
  "errors": []
}

Pri chybe je data rovné null a pole errors obsahuje stabilný strojový kód, ľudský popis a prípadné detaily.

Čas, časové pásmo a jednotky

Všetky okamihy na vstupe aj výstupe sú celé UNIX timestampy v sekundách. Ide o absolútny UTC okamih; klient si ho zobrazuje vo vlastnom časovom pásme. Denné štatistiky sú zostavené podľa kalendárneho dňa stanice v pásme Europe/Bratislava, no day je opäť vrátený ako UNIX timestamp.

Meteostanice

Stránkovaný zoznam aktívnych verejných staníc dostupných pre daný kľúč.

GET /api/v3/stations?page=1&per_page=30&networks=emeteo&include_current=1

{station} môže byť číselné ID alebo slug. Ak sa slug opakuje vo viacerých sieťach, doplňte ?network=.... Detail obsahuje polohu, zdroj dát, sieť, dostupné veličiny a webkamery.

{
  "data": {
    "id": 27,
    "slug": "banska-bystrica-zelena",
    "name": "Banská Bystrica-Zelená",
    "network": "emeteo",
    "data_source": "station",
    "latitude": 48.736,
    "longitude": 19.146,
    "altitude_m": 362,
    "created_at": 1478012400,
    "last_connection_at": 1790344710,
    "capabilities": ["temperature", "humidity", "pressure", "wind_speed"]
  },
  "meta": { "request_id": "…", "api_version": "3.0", "generated_at": 1790344800 },
  "errors": []
}

Aktuálne údaje

curl -H "Authorization: Bearer em3_VAS_KLUC" \
  "https://emeteo.sk/api/v3/stations/banska-bystrica-zelena/current?sea_level_pressure=1&daily_statistics=1"

{
  "data": {
    "station": {"id": 27, "slug": "banska-bystrica-zelena", "name": "Banská Bystrica-Zelená", "network": "emeteo"},
    "weather": {
      "measured_at": 1790344710,
      "temperature": 18.7,
      "humidity": 64.2,
      "pressure": 978.4,
      "pressure_sea_level": 1021.1,
      "wind_speed": 1.8,
      "wind_gust": 4.2,
      "wind_direction": 218,
      "rain": 0.4,
      "sunrise_at": 1790299200,
      "sunset_at": 1790342710
    }
  },
  "meta": {"units": {"temperature": "°C", "pressure": "hPa", "wind_speed": "m/s"}},
  "errors": []
}

Nemerená alebo momentálne nedostupná veličina má hodnotu null, nie nulu ani textovú pomlčku.

Historické merania

Surové alebo agregované merania v presnom rozsahu. Parametre from a to sú povinné UNIX timestampy v sekundách a obe hranice sú zahrnuté.

Dostupné typy:

temperaturehumiditypressurewind_speedwind_gustwind_directionrainsolar_radiationuvtemperature_above_5temperature_under_5temperature_under_10temperature_under_20temperature_under_50temperature_under_100humidity_above_5humidity_under_10humidity_under_20humidity_under_50

GET /api/v3/stations/27/measurements
    ?from=1790265600
    &to=1790351999
    &types=temperature,humidity,pressure
    &interval=300

{
  "data": {
    "station": {"id": 27, "slug": "banska-bystrica-zelena", "name": "Banská Bystrica-Zelená", "network": "emeteo"},
    "series": {
      "temperature": {
        "unit": "°C",
        "values": [
          {"time": 1790265600, "value": 12.84, "samples": 5},
          {"time": 1790265900, "value": 12.79, "samples": 5}
        ]
      }
    }
  },
  "meta": {"range": {"from": 1790265600, "to": 1790351999}, "interval": 300, "row_count": 288, "rain_mode": "daily_cumulative"},
  "errors": []
}

Časová rada s praktickými predvolenými hodnotami

Rovnaký formát ako measurements, no bez rozsahu použije aktuálny deň a bez parametra interval päťminútové agregácie.

Pri zrážkach sledujte meta.rain_mode: hodnota incremental znamená prírastky zrážok a daily_cumulative priebežný denný úhrn, ktorý sa môže pri zmene dňa vynulovať.

Denné a ročné štatistiky

Parameter type môže byť temperature, avg_temperature, pressure, wind, rain, solar_radiation alebo uv. Pri tlaku možno použiť sea_level_pressure=1; výsledné value bude redukované na hladinu mora a pôvodná hodnota zostane vo value_raw.

GET /api/v3/stations/27/statistics/2026?type=temperature

{
  "data": {
    "station": {"id": 27, "slug": "banska-bystrica-zelena", "name": "Banská Bystrica-Zelená", "network": "emeteo"},
    "year": 2026,
    "type": "temperature",
    "values": [
      {"day": 1788213600, "measurement": "temperature", "aggregation": "min", "value": 8.2, "measured_at": 1788237420},
      {"day": 1788213600, "measurement": "temperature", "aggregation": "max", "value": 21.7, "measured_at": 1788262320}
    ]
  },
  "meta": {"range": {"from": 1767222000, "to": 1798757999}, "row_count": 365},
  "errors": []
}

Webkamery

Stránkovaný zoznam verejných webkamier. Parametre page a per_page fungujú rovnako ako pri staniciach; obmedzenie staníc na API kľúči sa uplatní aj tu.

Využitie a limity kľúča

Vráti platnosť kľúča, limity, počet volaní za minútu/hodinu/deň a súhrn posledných 24 hodín podľa endpointu. Je vhodný pre diagnostiku klienta a sledovanie kvóty.

HTTP stavy a chyby

Klient sa má rozhodovať podľa stabilného errors[].code, nie podľa textu v poli message. Po odpovedi 429 počkajte počet sekúnd uvedený v Retry-After; odpovede 500 a 503 opakujte s exponenciálnym oneskorením a náhodným rozptylom.

{
  "data": null,
  "meta": {"request_id": "6f3b…", "api_version": "3.0", "generated_at": 1790344800},
  "errors": [{
    "code": "time_range_too_large",
    "message": "Requested time range exceeds the API key limit.",
    "details": {"max_range_seconds": 2678400}
  }]
}

Príklady integrácie

JavaScript (fetch)

const response = await fetch(
  'https://emeteo.sk/api/v3/stations/27/measurements' +
  '?from=1790265600&to=1790351999&types=temperature&interval=300',
  { headers: { 'X-API-Key': 'em3_VAS_KLUC' } }
);

const body = await response.json();
if (!response.ok) throw new Error(body.errors?.[0]?.message ?? 'API error');
console.log(body.data.series.temperature.values);

PHP (cURL)

$curl = curl_init('https://emeteo.sk/api/v3/stations/27/current');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: em3_VAS_KLUC'],
]);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);