Data Hub pro agentury a vývojáře

Co je Data Hub

Data Hub je ověřený zdroj pravdy o lyžařském resortu SkiResort ČERNÁ HORA – PEC: areály, lanovky a vleky, sjezdovky, běžecké tratě, služby a místa, skibusy, produkty (skipasy), věkové kategorie, ceníky a glosář pojmů. Slouží webu a e-shopu (agenturám), vlastním kanálům resortu (TV panorama, displeje, aplikace) i AI asistentům.

Každý údaj je claim se zdrojem (URL, doslovný úryvek, čas stažení, důvěra). Pravidla priority zdrojů vyberou publikovanou hodnotu a rozpory se nerozhodují potichu (_conflicts, přehled kvality). Publikuje se neměnný release – API, fact pages, llms-full.txt i MCP čtou tentýž release, takže říkají totéž.

Rychlý start

Čtení je bez autentizace, CORS je *, odpovědi jsou cacheovatelné. První volání:

curl -s 'https://data.skiresort.cz/api/v2/lifts?area=cerna-hora&lang=cs'
curl -s 'https://data.skiresort.cz/api/v2/status?area=pec'
curl -s -D - -o /dev/null -H 'If-None-Match: "<ETag z předchozí odpovědi>"' 'https://data.skiresort.cz/api/v2/lifts'   # → 304
curl -s -H 'Accept: application/ld+json' 'https://data.skiresort.cz/api/v2/lifts/lift:cerna-hora:a1'          # JSON-LD (schema.org)
curl -s 'https://data.skiresort.cz/lifts/cerna-hora/a1.md'                                                       # Markdown fact page

// Prohlížeč nebo Node.js – podmíněný požadavek s ETag
let etag;
async function refreshLifts() {
  const r = await fetch("https://data.skiresort.cz/api/v2/lifts?area=cerna-hora", { headers: etag ? { "If-None-Match": etag } : {} });
  if (r.status === 304) return null; // beze změny
  etag = r.headers.get("ETag");
  const { data, meta } = await r.json();
  return { lifts: data, release: meta.release, attribution: meta.attribution };
}

import json, urllib.request
req = urllib.request.Request("https://data.skiresort.cz/api/v2/age-categories", headers={"Accept": "application/json", "User-Agent": "agentura-xy/1.0 (+kontakt)"})
print(json.load(urllib.request.urlopen(req))["data"])

Co je co: typy entit a kolekce

Data mají vrstvy: M master (místa, zařízení), O provoz (živé stavy, rozvrhy, pozorování), C obchod (produkty, věk, ceny), K obsah (glosář, FAQ, texty), G governance (zdroje, kvalita). Každý typ entity má jednu kolekci /api/v2/{kolekce} a detail /api/v2/{kolekce}/{id}; atributy popisuje datový slovník.

Souhrnné pohledy: /status (živý provoz), /weather (teploty z kamer), /prices (ceník sezóny), /age-categories (věkové sady s kontrolou pokrytí), /search?q=, /releases/latest, /quality.

Identifikátory

• Kanonické ID má tvar {typ}:{areál}:{označení} (lift:cerna-hora:a1, slope:pec:7), u entit celého resortu {typ}:{označení} (product:flexiskipas, season:2026-27). Je neměnné a nikdy se nerecykluje; jako klíč používejte ID, ne název.
• Areály: area:cerna-hora, area:pec, area:velka-upa, area:cerny-dul, area:svoboda a partnerská area:mala-upa (membership: partner).
• Staré klíče a cizí ID jsou aliasy: /api/v2/entities/lift:chora:A1 (klíč v1), lift-cerna-hora-a1 (mapa webu), chora/loc_lifts/A1 (Holidayinfo) → 301 na kanonické ID. Cizí identifikátory jsou v externalIds (osm, wikidata, eshop…).
• Přejmenování = nový alias; sloučení = replacedBy + 301; zrušení = tombstone + 410.
• URI identity pro propojená data: https://data.skiresort.cz/id/{typ}/{…} (JSON-LD @id) – zatím jen stabilní identifikátory (nedereferencují se); pro data použijte fact page nebo API.

Stav ≠ schopnost ≠ rozvrh

• Stav (operations.sessions[]): open | partial | hold | scheduled | closed | unknown pro relaci day, evening, night nebo summer-day (provoz mimo zimní sezónu – pěší, kola), vždy s observedAt (kdy zdroj stav zjistil) a validUntil (do kdy platí bez nového potvrzení).
• Po validUntil bez potvrzení vrací API status: unknown, stale: true a lastKnown. unknown neznamená zavřeno.
• Mimo zimní sezónu se stav lyžování nepublikuje: sjezdovky a tratě jsou closed s reason: off-season, původní stav zdroje je v sourceStatus; souhrnná věta to říká výslovně.
• Schopnost (nightSkiingCapable, snowmakingCapable) je vlastnost sjezdovky (osvětlení, zasněžování), ne dnešní provoz. Dnešní večerní lyžování = relace evening ve /status.
• Rozvrh (operatingHours, operatingScheduleRule, vzor pattern: sat-sun) popisuje plán, ne skutečnost.
• Booleany jsou tří-stavové (true | false | null); null má důvod v unknownReasons.

Čas, jazyk, formáty

• Časy RFC 3339 s offsetem Europe/Prague (2026-10-17T09:32:38+02:00), data YYYY-MM-DD; meta.timezone = "Europe/Prague".
• Jazyk ?lang=cs|en|de|pl nebo Accept-Language; chybějící překlad spadne na češtinu (meta.notes, Content-Language).
• Formáty: JSON (výchozí); detail entity také Accept: application/ld+json (schema.org) a Accept: text/markdown; fact pages /lifts/cerna-hora/a1 (HTML) a /lifts/cerna-hora/a1.md; nepodporovaný Accept → 406.
• Kolekce se stránkují: limit (výchozí 100, max 500) a cursor z links.next.

Cache, čerstvost a slušné chování

• Posílejte If-None-Match s ETag (→ 304 bez těla). ETag se mění s novým releasem i s vypršením živého stavu.
• /status pollujte nejvýš 1× za 30 s, master data 1× za 5 min. Uvádějte User-Agent s kontaktem.
• meta.stale: true = release nebo živé údaje jsou starší než cíl čerstvosti; zobrazte čas observedAt.

Verze a kompatibilita

• Major verze je v URL (/api/v2), meta.schemaVersion je semver datového kontraktu (aktuálně 2.1.0).
• Klient musí ignorovat neznámá pole a tolerovat nové hodnoty enumů – registr roste aditivně (nový atribut = minor).
• Rušení pole nebo parametru: deprecated v OpenAPI + changelog, souběh ≥ 6 měsíců, hlavičky Deprecation/Sunset.
• API v1 (/api/v1/*) zůstává beze změny chování do ukončení (plán: 30. 6. 2027), viz migrace v1 → v2.

Chyby

Chyby jsou application/problem+json (RFC 9457) s akční radou: invalid-parameter (400, errors[] s povolenými hodnotami), invalid-id (400), not-found (404, suggestions[]), method-not-allowed (405), not-acceptable (406, supported[]), gone / cursor-expired (410), uri-too-long (414), release-unavailable (503, Retry-After).

Licence a atribuce

Zobrazujte meta.attributions (atribuce Data Hubu a zdrojů použitých v odpovědi: sourceId, text, licence, url). Podrobnosti a stav licencí: Licence a atribuce.

Kontroly kvality dat

Kontroly běží při stavbě každého releasu (výsledek je součástí releasu) a v okamžiku požadavku (čerstvost živých dat). Přehled: /api/v2/quality (checks[]: id, severity, result, stage, action, gate, count, affected, detail, data). Kontrola s gate: true a výsledkem fail release nepublikuje – API dál vrací předchozí release a živé stavy po validUntil přejdou na unknown.

Kontakt a nahlášení chyby v datech

Chybný údaj nahlaste s ID entity a URL fact page (každá stránka má sekci „Jak tato data vznikají“). Kontaktní adresa Data Hubu pro agentury se zřizuje; do té doby přes kontakt provozovatele na www.skiresort.cz.

Dokumentace

• 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.
• 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.