Limity a odolnost

Rate limity (Cloudflare a aplikace), hlavičky RateLimit-*, 429 a jak se chovat slušně.

API v2 · schemaVersion 2.2.0 · release m-2f73b3 (2026-10-22T09:35:04+02:00)

Tři vrstvy ochrany

Veřejné čtení (API v2, MCP, fact pages) je bez přihlášení. Proti přetížení chrání tři vrstvy:

Vrstva	Rozsah	Limit	Odpověď při překročení
Cloudflare (edge)	jen `/mcp` a `/api/v2/search`	300 požadavků / 10 s / IP	429 jako HTML stránka Cloudflare (bez problem+json)
Aplikace – anonym	`/mcp` a `/api/v2/search`	600 požadavků / min / IP	429 `application/problem+json`, `Retry-After`
Aplikace – partnerský klíč	`/mcp` a `/api/v2/search`	6 000 požadavků / min / klíč	429 `application/problem+json`, `Retry-After`

Ostatní cesty (ostatní API v2, /status, fact pages, docs, OpenAPI) aplikační limit nemají; OPTIONS (CORS preflight) se nepočítá. Okno je klouzavé (1 min).
Limitované cesty vracejí Cache-Control: private, no-store a na každé odpovědi (i 200) RateLimit-Policy (např. 600;w=60) a RateLimit-Remaining. Při 429 je RateLimit-Remaining: 0, Retry-After v sekundách a tělo problem+json (retryAfter, limit, windowSeconds).
IP klienta se bere z CF-Connecting-IP; partnerský klíč se posílá jako Authorization: Bearer … nebo X-Hub-Key: …. Neplatný klíč nikdy nevrací 401 – počítá se jako anonym.

Cachujte podle Cache-Control a posílejte If-None-Match s posledním ETag – odpověď 304 je levná.
/status pollujte nejvýš 1× za 30 s, master data 1× za 5 min; /api/v2/search nevolejte na každý stisk klávesy (debounce).
Po 429 počkejte Retry-After, neopakujte okamžitě. Uvádějte User-Agent s kontaktem.
Vyšší limit nebo partnerský klíč: přes kontakt provozovatele na www.skiresort.cz.

Data Hub pro agentury a vývojáře – Co Data Hub obsahuje, jak číst identifikátory, stavy, čas, cache, verze a licence – s příklady volání.
API reference (OpenAPI 3.1) – Interaktivní reference veřejného API v2 generovaná z OpenAPI 3.1.
Datový slovník – Typy entit a jejich atributy z registru domény: jednotky, vrstvy, rodiny, časovost a mapování.
Číselníky – Kódy typů lanovek, obtížností, stavů, relací, důvodů, sezónních fází, kategorií služeb a druhů zdrojů.
Glosář pojmů – Pojmy resortu (SkiTour, Flexiskipas, sKiosek…) s definicemi z aktuálního releasu.
Pro AI agenty: MCP, OpenAPI a llms.txt – Read-only MCP server, nástroje, limity a jak citovat data.
Changelog – Změny produktu a schématu API v2.
Politika verzí a zralost API – Co znamená stable a beta, stav kolekcí (implemented, derived-view, planned, deprecated) a jak se ohlašují změny.
Licence a atribuce – Za jakých podmínek lze data použít a jak uvádět zdroje.
Migrace z API v1 na v2 – Mapování polí a identifikátorů v1 → v2 a harmonogram ukončení v1.
Správa dat a vlastníci kategorií – Kdo odpovídá za kterou kategorii údajů, jak se data mění, schvalují a publikují.
Limity a odolnost – Rate limity (Cloudflare a aplikace), hlavičky RateLimit-*, 429 a jak se chovat slušně.