vodnistav.cz
TokyStaniceCeníkDokumentace APIPřihlásit se
Reklama 728×90

Dokumentace API

Veřejné API aplikace vodnistav.cz poskytuje přístup k hydrologickým datům z ČHMÚ — vodní stavy a průtoky na řekách v České republice. API je dostupné ve dvou variantách: REST a GraphQL.

Base URL: https://vodnistav.cz

Autentizace

Všechny požadavky na veřejné API vyžadují API klíč zaslaný v hlavičce X-API-Key.

bash
curl -H "X-API-Key: vsc_váš_klíč" https://vodnistav.cz/api/v1/stations

Test vs Live mód

Každý API klíč má nastavený mód — test nebo live. Testovací klíče (výchozí) vrací fake data s reálnou strukturou odpovědí, ideální pro vývoj a testování integrace. Mají rate limit 60 požadavků/min. Live klíče vrací skutečná hydrologická data z ČHMÚ bez limitu požadavků. Podrobnosti a ceny najdete na stránce Ceník.

REST API

REST API je dostupné pod prefixem /api/v1/. Všechny odpovědi jsou ve formátu JSON s obálkou { "data": ..., "meta": ... }.

Stanice

GET

/api/v1/stations

Vrátí seznam všech aktivních měřicích stanic.

Příklad odpovědi:
json
{
  "data": [
    {
      "id": 1,
      "id_external": "123456",
      "code": "ABC",
      "name": "Praha - Chuchle",
      "river_name": "Vltava",
      "basin_name": "Vltava",
      "lat": 50.0,
      "lon": 14.4,
      "elevation_m": 190.0,
      "is_active": true
    }
  ],
  "meta": { "count": 1 }
}
GET

/api/v1/stations/:id

Vrátí detail jedné stanice.

Parametry cesty:
ParametrTypPopis
idnumberID stanice
GET

/api/v1/stations/:id/measurements

Vrátí měření dané stanice za zvolené období.

Query parametry:
ParametrVýchozíPopis
period3dRelativní období: 24h, 3d, 7d, 30d
from—Začátek rozsahu (YYYY-MM-DD). Má přednost před period.
to—Konec rozsahu (YYYY-MM-DD, exkluzivní). Vyžaduje from.
Příklady:
bash
# Relativní období
curl -H "X-API-Key: vsc_..." "https://vodnistav.cz/api/v1/stations/1/measurements?period=7d"

# Konkrétní měsíc
curl -H "X-API-Key: vsc_..." "https://vodnistav.cz/api/v1/stations/1/measurements?from=2025-01-01&to=2025-02-01"
GET

/api/v1/stations/:id/measurements/availability

Vrátí přehled dostupných dat — roky a měsíce, pro které existují měření. Volitelně vrátí dostupné dny v konkrétním měsíci.

Query parametry (volitelné):
ParametrPopis
yearRok (spolu s month vrátí dostupné dny)
monthMěsíc (1–12, vyžaduje year)
Příklad odpovědi (bez parametrů):
json
{
  "data": {
    "years": [2024, 2025, 2026],
    "months": {
      "2024": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
      "2025": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
      "2026": [1, 2]
    }
  }
}
Příklad odpovědi (s year + month):
json
{
  "data": {
    "days": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
  }
}

Toky

GET

/api/v1/rivers

Vrátí seznam toků s aktivními stanicemi.

Příklad odpovědi:
json
{
  "data": [
    {
      "id": 1,
      "name": "Vltava",
      "basin_name": "Vltava",
      "station_count": 12,
      "latest_avg_discharge_m3s": 85.5
    }
  ],
  "meta": { "count": 1 }
}
GET

/api/v1/rivers/:id

Vrátí detail jednoho toku.

GET

/api/v1/rivers/:id/measurements

Vrátí agregovaná měření pro celý tok.

Query parametry:
ParametrVýchozíPopis
granularityhourGranularita: 10min, hour, day, month, year
period3dRelativní období: 24h, 3d, 7d, 30d, 90d, 1y, 5y, all
from—Začátek rozsahu (YYYY-MM-DD). Má přednost před period.
to—Konec rozsahu (YYYY-MM-DD, exkluzivní). Vyžaduje from.
GET

/api/v1/rivers/:id/measurements/availability

Vrátí přehled dostupných dat pro tok — roky a měsíce, volitelně dny.

Funguje stejně jako /api/v1/stations/:id/measurements/availability — viz výše.

GraphQL API

GraphQL endpoint: POST /api/graphql (s hlavičkou X-API-Key). Interaktivní GraphiQL průzkumník je dostupný na GET /api/graphql.

Schéma

SDL schéma si můžete stáhnout na GET /api/graphql/schema (bez autentizace). Introspekce je také povolena — GraphQL klienti jako Apollo nebo Relay si schéma stáhnou automaticky.

bash
# Stažení SDL schématu
curl -o schema.graphql https://vodnistav.cz/api/graphql/schema
Příklad dotazu:
graphql
query {
  stations {
    id
    name
    riverName
    measurements(period: _7D) {
      ts
      waterLevelCm
      dischargeM3s
    }
  }
}
Dotaz s vlastním rozsahem dat:
graphql
query {
  station(id: 1) {
    name
    measurements(from: "2025-01-01", to: "2025-02-01") {
      ts
      waterLevelCm
      dischargeM3s
    }
    availability {
      years
      yearMonths {
        year
        months
      }
    }
  }
}
Příklad volání:
bash
curl -X POST https://vodnistav.cz/api/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vsc_..." \
  -d '{"query": "{ stations { id name riverName } }"}'

TypeScript typy

Pro typově bezpečnou práci s API můžete použít následující TypeScript definice:

Datové typy
typescript
interface Station {
  id: number;
  id_external: string;
  code: string | null;
  name: string;
  river_name: string | null;
  basin_name: string | null;
  lat: number | null;
  lon: number | null;
  elevation_m: number | null;
  is_active: boolean;
}

interface Measurement {
  ts: string;
  water_level_cm: number | null;
  discharge_m3s: number | null;
}

interface River {
  id: number;
  name: string;
  basin_name: string | null;
  station_count: number;
  latest_avg_discharge_m3s: number | null;
}
Enumy
typescript
type Period = '24h' | '3d' | '7d' | '30d';
type Granularity = '10min' | 'hour' | 'day' | 'month' | 'year';
type RiverPeriod = '24h' | '3d' | '7d' | '30d' | '90d' | '1y' | '5y' | 'all';
Response obálky
typescript
interface ApiSuccessResponse<T, M extends Record<string, unknown> = Record<string, never>> {
  data: T;
  meta?: M;
}

interface ApiErrorResponse {
  error: { message: string; status: number };
}

// Konkrétní response typy per endpoint
type StationsResponse = ApiSuccessResponse<Station[], { count: number }>;
type StationResponse = ApiSuccessResponse<Station>;
type StationMeasurementsResponse = ApiSuccessResponse<
  Measurement[],
  { count: number; period: Period; from?: string; to?: string }
>;
type RiversResponse = ApiSuccessResponse<River[], { count: number }>;
type RiverResponse = ApiSuccessResponse<River>;
type RiverMeasurementsResponse = ApiSuccessResponse<
  Measurement[],
  { count: number; granularity: Granularity; period: RiverPeriod; from?: string; to?: string }
>;

Formáty odpovědí

Úspěšná odpověď
json
{
  "data": [...],
  "meta": {
    "count": 42,
    "period": "3d"
  }
}
Chybová odpověď
json
{
  "error": {
    "message": "Chybí API klíč. Přidejte header X-API-Key.",
    "status": 401
  }
}

Časové značky (ts) jsou ve formátu ISO 8601 s časovou zónou (UTC).

Příklady použití

curl
bash
# Seznam stanic
curl -H "X-API-Key: vsc_váš_klíč" https://vodnistav.cz/api/v1/stations

# Měření stanice za 7 dnů
curl -H "X-API-Key: vsc_váš_klíč" "https://vodnistav.cz/api/v1/stations/1/measurements?period=7d"

# Měření za leden 2025
curl -H "X-API-Key: vsc_váš_klíč" "https://vodnistav.cz/api/v1/stations/1/measurements?from=2025-01-01&to=2025-02-01"

# Dostupnost dat stanice
curl -H "X-API-Key: vsc_váš_klíč" https://vodnistav.cz/api/v1/stations/1/measurements/availability

# Seznam toků
curl -H "X-API-Key: vsc_váš_klíč" https://vodnistav.cz/api/v1/rivers
JavaScript (fetch)
javascript
const API_KEY = 'vsc_váš_klíč';

const res = await fetch('https://vodnistav.cz/api/v1/stations', {
  headers: { 'X-API-Key': API_KEY },
});
const { data, meta } = await res.json();
console.log(`Načteno ${meta.count} stanic`);
Python (requests)
python
import requests

API_KEY = "vsc_váš_klíč"
headers = {"X-API-Key": API_KEY}

res = requests.get("https://vodnistav.cz/api/v1/stations", headers=headers)
data = res.json()
print(f"Načteno {data['meta']['count']} stanic")
Reklama 728×90