Protokol DatováMapa 0.1

Normativní popis rozhraní mezi poskytovatelem dat a portálem. Při rozporu s jinou dokumentací platí tento dokument a strojová schémata:

• JSON Schema manifestu a JSON Schema dat – generované ze zod schémat v src/lib/protocol/,
• OpenAPI kontrakt poskytovatele.

Postup přípravy dat krok za krokem (zejména pro AI agenty) je v návodu pro AI agenty, srozumitelný úvod v průvodci pro poskytovatele. Platné vzory: manifest-kompletni.json, data-body.json.

Přehled

Poskytovatel                         Portál DatováMapa                 Prohlížeč
─────────────                        ─────────────────                 ─────────
manifest.json  ◄── GET (cache 10 min) ── registr → katalog ──────────► /api/katalog
data endpoint  ◄── GET ?bbox&zoom&… ──── proxy + validace + cache ───► /api/data/{provider}/{dataset}
rastrové dlaždice ◄───────────────────────────────────────────────────── přímo z prohlížeče

Obecná pravidla

• Formát JSON, kódování UTF-8, souřadnice WGS84 (EPSG:4326) v pořadí [lon, lat].
• Komunikace přes HTTPS (http jen pro localhost při vývoji).
• Neznámá pole se ignorují. Neznámý typ presentation se vykreslí jako auto.
• Verze protocol ve tvaru major.minor. Portál přijme manifest se stejnou hlavní verzí.
• Identifikátory (provider.id, dataset.id): malá písmena bez diakritiky, číslice, pomlčky, max. 64 znaků. Globální klíč sady je provider/dataset.
• Barvy jen v hex zápisu (#rgb, #rrggbb, #rrggbbaa).

Manifest

Datová sada

source

geojson – nativní formát.

{ "type": "geojson", "url": "/data/kontejnery", "mode": "bbox", "maxFeatures": 5000 }

• url může být relativní vůči URL manifestu. Zdrojem může být i statický soubor (lavicky.geojson vedle manifest.json na libovolném webovém hostingu) – v režimu full portál žádné query parametry nevyžaduje a soubor je platný endpoint.
• mode: "full" – celá sada jedním dotazem (malé sady). mode: "bbox" – portál se ptá na výřez mapy.
• maxFeatures ≤ 5000.

raster – hotové dlaždice, prohlížeč je načítá přímo ze zdroje.

{ "type": "raster", "tiles": ["https://…/{z}/{x}/{y}.png"], "tileSize": 256, "minZoom": 0, "maxZoom": 19 }

Šablony podporují {z}/{x}/{y} i {bbox-epsg-3857} (WMS GetMap). Jen https.

presentation

Všechny typy mají volitelnou legend: [{ label, color }] (max. 20 položek). Portál ji ukazuje v legendě přímo v mapě a ve výběru vrstev. U vektorových typů ji umí odvodit z barev, u raster ne – barvy jsou zapečené v obrázcích dlaždic, takže legendu rastru uveďte ručně (např. převzetím z legendy WMS / ArcGIS služby).

Barva (color) je buď hex řetězec, nebo pravidlo podle vlastnosti objektu:

{ "field": "druh", "type": "categorical", "values": { "papír": "#2563eb" }, "default": "#64748b" }
{ "field": "hodnota", "type": "interpolate", "stops": [[0, "#f7fcb9"], [100, "#004529"]] }
{ "field": "hodnota", "type": "step", "default": "#eee", "stops": [[10, "#fc8"], [50, "#e34"]] }
{ "type": "trend" }

trend barví objekty podle toho, zda jejich hodnota v čase roste, stagnuje, nebo klesá. Počítá ho portál z grafu vývoje dm.chart – viz vývoj v čase a trend.

Číslo (radius, width, weight) je číslo nebo { "field", "type": "interpolate", "stops": [[hodnota, číslo], …] }.

Popisek (label): { field, minZoom?, color?, size? }.

params

Filtr, který uživatel nastaví v portálu; portál ho pošle jako query parametr key=value.

Klíče bbox, zoom, limit, cursor, lang, protocol jsou rezervované. Portál posílá jen deklarované parametry a hodnoty předem ověří; nevyplněný parametr nahradí default.

Časový filtr

Data v čase (nehody, měření, události) mají jeden parametr pro období a odkazují na něj z temporal.param. Portál ho pak neukazuje mezi ostatními filtry, ale jako časovou osu v okně pod legendou: posuvník období a sloupcový graf po letech, ve kterém jde období vybrat kliknutím nebo tažením. Zvolené období je vidět i u vrstvy v legendě.

• Typ range s roky – min a max jsou první a poslední rok dat, hodnota od,do (např. 2019,2023, jeden rok 2023,2023). Objekty za celé období vracejte dohromady (souhrnně), ne po jednotlivých letech.
• Typ date-range – období po dnech, 2026-01-01,2026-06-30.

{
  "protocol": "0.1",
  "provider": { "id": "mesto-priklad", "name": "Město Příklad" },
  "license": { "name": "CC BY 4.0", "attribution": "© Město Příklad" },
  "datasets": [{
    "id": "nehody",
    "title": "Dopravní nehody",
    "description": "Nehody evidované Policií ČR podle následků.",
    "category": "doprava",
    "keywords": ["nehoda", "dopravní nehoda", "bezpečnost", "zranění", "křižovatka"],
    "useCases": ["doprava", "bydleni"],
    "coverage": { "bbox": [16.43, 49.1, 16.73, 49.3], "minZoom": 12 },
    "temporal": { "frequency": "ročně", "param": "obdobi" },
    "source": { "type": "geojson", "url": "https://data.mesto-priklad.cz/datovamapa/nehody", "mode": "bbox", "maxFeatures": 5000 },
    "presentation": {
      "type": "circle",
      "color": { "field": "nasledky", "type": "categorical", "values": { "zranění": "#dc2626", "hmotná škoda": "#facc15" }, "default": "#facc15" }
    },
    "fields": [
      { "key": "nasledky", "label": "Následky", "type": "string", "primary": true },
      { "key": "datum", "label": "Datum", "type": "date" }
    ],
    "params": [{ "key": "obdobi", "label": "Období", "type": "range", "min": 2015, "max": 2025, "step": 1, "default": "2025,2025" }]
  }]
}

Graf kreslí portál z dm.timeline v odpovědi (viz datová odpověď). Bez něj zůstane jen posuvník období.

Vývoj v čase a trend

Standardní zobrazení dat, jejichž hodnota se u objektu mění v čase – počet obyvatel obce, cena, naměřená koncentrace, návštěvnost. Kdykoli data takovou řadu mají, posílejte ji; portál z ní sám kreslí graf a umí podle ní barvit.

• Graf vývoje. Má-li objekt hodnotu za více období, pošlete ji v feature.dm.chart (viz datová odpověď). Portál ji ukáže v detailu objektu jako čárový graf s hodnotou za zvolené období a změnou proti jeho začátku. Platí to i pro kartogramy, kde se rok volí parametrem: pošlete řadu za všechny roky a zvolený rok jako highlight se stejným from a to. Když sada barví podle číselné hodnoty, období se volí parametrem a graf chybí, validátor to hlásí jako chybi_graf_vyvoje.
• Barva podle trendu. Je-li smyslem sady změna („roste, nebo ubývá?“), nastavte color: { "type": "trend" }. Portál z grafu každého objektu spočítá průměrnou změnu za jedno období v % počáteční hodnoty – ve zvýrazněném období (highlight), jinak za celou řadu. Od threshold (výchozí 0,5 %) výš hodnota roste (zelená), od −threshold níž klesá (červená), mezi tím stagnuje (šedá). Barvy lze přepsat přes colors: { up, flat, down }, třeba když je růst nežádoucí. Legendu portál odvodí sám a graf v detailu obarví stejně jako objekt v mapě. Objekt bez grafu zůstane světle šedý (trend_bez_grafu).

Trend vychází z relativní změny, hodí se proto pro kladné veličiny (počty, ceny, koncentrace). Hodnoty kolem nuly, jako saldo stěhování, barvěte přes interpolate a vývoj ukažte jen grafem.

{
  "protocol": "0.1",
  "provider": { "id": "kraj-priklad", "name": "Kraj Příklad" },
  "license": { "name": "CC BY 4.0", "attribution": "© Kraj Příklad" },
  "datasets": [{
    "id": "vyvoj-obyvatel",
    "title": "Vývoj počtu obyvatel obcí",
    "description": "Kde obyvatel přibývá a kde ubývá. Barva podle trendu ve zvoleném období, v detailu obce graf po letech.",
    "category": "spolecnost",
    "keywords": ["obyvatelé", "vývoj", "trend", "růst", "vylidňování"],
    "useCases": ["bydleni", "verejna-sprava"],
    "temporal": { "frequency": "ročně", "param": "obdobi" },
    "source": { "type": "geojson", "url": "https://data.kraj-priklad.cz/datovamapa/obyvatele" },
    "presentation": { "type": "circle", "color": { "type": "trend", "threshold": 0.5 }, "radius": 7 },
    "fields": [
      { "key": "nazev", "label": "Obec", "type": "string", "primary": true },
      { "key": "obyvatel", "label": "Obyvatel na konci období", "type": "integer" }
    ],
    "params": [{ "key": "obdobi", "label": "Období", "type": "range", "min": 2015, "max": 2025, "step": 1, "default": "2015,2025" }]
  }]
}

Odpověď pak u každé obce posílá řadu za všechny roky a zvolené období v highlight, například { "from": "2015", "to": "2025" }.

Datový dotaz

GET {source.url}?bbox=minLon,minLat,maxLon,maxLat&zoom=10&limit=5000&lang=cs&protocol=0.1[&cursor=…][&{params}]
Accept: application/geo+json, application/json
User-Agent: DatovaMapa/0.1 (+https://datovamapa.cz/dokumentace/pro-poskytovatele)

• bbox a zoom jen v režimu bbox. Výřez je zarovnaný na dlaždice úrovně zoom (celé číslo), takže blízké pohledy vedou na stejný dotaz – poskytovatel i portál mohou odpovědi cachovat.
• limit = kolik objektů portál nanejvýš zpracuje.
• Časový limit odpovědi 10 s, velikost max. 15 MB.

Datová odpověď

GeoJSON FeatureCollection (RFC 7946). Podporované geometrie: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon. Objekty s geometry: null se přeskočí.

Volitelná rozšíření:

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature", "id": 1, "geometry": {…}, "properties": {…},
    "dm": { "title": "…", "description": "…", "url": "https://…", "color": "#e11d48", "chart": {…} }
  }],
  "dm": { "generated": "2026-10-06T08:00:00Z", "ttl": 3600, "total": 1, "truncated": false, "next": "…", "notice": "…", "timeline": […] }
}

• feature.dm – nadpis a popis v detailu, odkaz na detail u zdroje, přepsání barvy, graf vývoje.
• feature.dm.chart – vývoj jedné hodnoty objektu v čase, který portál nakreslí v detailu objektu jako čárový graf s hodnotou za poslední období (např. počet obyvatel obce po letech) a ze kterého počítá barvu podle trendu. label říká, co graf ukazuje, nepovinné unit, decimals, note (poznámka pod grafem, např. o změně metodiky) a highlight: { from, to } – zvýrazněné období, typicky zvolené v časovém filtru; portál ho podbarví, ukáže hodnotu na jeho konci a změnu i trend počítá od jeho začátku. Stejné from a to označí jedno období, např. rok zvolený u kartogramu – graf se na něm zastaví. points jsou dvojice { period, value } seřazené od nejstaršího období – period je rok, měsíc nebo den jako u dm.timeline. 2–100 bodů. Posílejte ho vždy, když má objekt hodnotu za více období (viz vývoj v čase a trend).
• dm.ttl – platnost odpovědi (portál použije menší z cache.ttl a dm.ttl).
• dm.total, dm.truncated – kolik objektů celkem / zda je odpověď zkrácená.
• dm.notice – krátké sdělení pro uživatele (zobrazí se u vrstvy).
• dm.next – kurzor na další stránku (portál ho zatím nevyužívá, rezervováno).
• dm.timeline – počty objektů ve výřezu po obdobích za celou dobu, kterou sada pokrývá, nezávisle na zvoleném období a na limit (spočítejte je agregačním dotazem, ne z vrácených objektů). Portál z nich kreslí graf u legendy. period je rok (2023), měsíc (2023-05) nebo den; nepovinné values rozdělí počet podle hodnot vlastnosti z color.field a graf je obarví jako legendu. Max. 400 období.

{
  "type": "FeatureCollection",
  "features": [],
  "dm": {
    "timeline": [
      { "period": "2024", "count": 2366, "values": { "zranění": 701, "hmotná škoda": 1665 } },
      { "period": "2025", "count": 1894, "values": { "zranění": 652, "hmotná škoda": 1242 } }
    ]
  }
}

Objekt s grafem vývoje v detailu:

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "id": "500496",
    "geometry": { "type": "Point", "coordinates": [17.2731, 49.5957] },
    "properties": { "nazev": "Olomouc", "obyvatel": 105297 },
    "dm": {
      "chart": {
        "label": "Počet obyvatel k 31. 12.",
        "points": [
          { "period": "2023", "value": 102293 },
          { "period": "2024", "value": 103063 },
          { "period": "2025", "value": 105297 }
        ]
      }
    }
  }]
}

• Vlastnosti s prefixem __dm_ jsou rezervované pro portál a z odpovědi se odstraní.

Cache

• Portál drží odpovědi po dobu min(cache.ttl, dm.ttl), výchozí 300 s. Manifesty 10 min.
• Po vypršení drží záznam ještě 24 h jako zálohu: když zdroj neodpovídá, ukáže poslední data s upozorněním.
• cache.store: false – poskytovatel nesouhlasí s trvalým uložením dat do datové vrstvy portálu (krátkodobé cachování odpovědí podle ttl platí dál).

Validace

Shodu s protokolem ověřuje validátor (POST /api/validovat, živý test GET /api/validovat?manifestUrl=…, nebo MCP nástroje validovat_manifest a validovat_data). Rozlišuje:

• chyby (errors) – porušení tohoto dokumentu; manifest s chybou portál nepřijme, data s chybou nezobrazí,
• doporučení (warnings) – data fungují, ale hůř se hledají, zobrazují nebo kombinují.

Každý nález má stabilní code (přehled kódů), cestu path a u doporučení radu hint. Kódy se mezi minor verzemi nemění, nové mohou přibývat.

Vývoj protokolu

• Nová volitelná pole a nové typy presentation / source = nová minor verze (0.2…).
• Změna významu existujících polí = nová major verze; portál po přechodnou dobu podporuje obě.
• Kandidáti na další verze: symbol (ikony), extrusion (3D), časová dimenze (time u objektů + parametr), vector-tiles / pmtiles / ogc-features jako zdroje, stránkování přes next, agregace pro malá přiblížení.