DatovaMapa.cz

Wersja do odczytu maszynowego: /pl/dokumentace/protokol.md

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:

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-complete.json, data-points.json.

Přehled

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

Obecná pravidla

Manifest

Pole Povinné Popis
protocol ano Verze protokolu, např. "0.1"
provider.id ano Identifikátor; musí odpovídat id v registru portálu
provider.name ano Název zobrazovaný jako zdroj
provider.description, homepage, logo, contact ne
provider.managedBy ne provider (výchozí) / portal – manifest pro veřejnou službu udržuje DatováMapa
license ne { name, url?, attribution } – výchozí licence všech sad
datasets[] ano 1–200 datových sad s unikátním id

Datová sada

Pole Povinné Popis
id, title ano
description ne
category ne territory, nature, water, risks, energy, transport, society, economy, infrastructure, sample, other; jiná hodnota → Ostatní
tags, keywords ne Pro vyhledávání a budoucího asistenta
useCases ne Účely, pro které se sada hodí: construction, housing, land-purchase, agriculture, investment…
coverage ne { bbox?, area?, minZoom?, maxZoom? } – pod minZoom portál data nenačítá
temporal ne { updated?, frequency?, param? } – param = klíč parametru, kterým se volí období (viz časový filtr)
license ne Přepisuje licenci poskytovatele
source ano Odkud data brát (viz níže)
presentation ano Jak data vykreslit (viz níže)
fields[] ne Popis vlastností objektů: key, label, type, unit, decimals, description, primary
params[] ne Filtry pro uživatele (viz níže)
cache ne { ttl?: sekundy, store?: boolean }

source

geojson – nativní formát.

{ "type": "geojson", "url": "/data/kontejnery", "mode": "bbox", "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

type Geometrie Volby
circle body color, radius, opacity, strokeColor, strokeWidth, label, cluster
heatmap body weight, radius, intensity, colors[], opacity
line linie color, width, opacity, dash[], label
fill plochy color, opacity, outlineColor, outlineWidth, label
raster dlaždice opacity
auto cokoli color

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.

type Hodnota v dotazu
enum key=a (z options)
multi-enum key=a,b,c
number key=42 (v rozsahu min–max)
range key=od,do
boolean key=true / false
date key=2026-10-06
date-range key=2026-01-01,2026-12-31
text key=… (max. 200 znaků)

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

{
  "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": "transport",
    "keywords": ["nehoda", "dopravní nehoda", "bezpečnost", "zranění", "křižovatka"],
    "useCases": ["transport", "housing"],
    "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ěď). U hodnot v čase, kde počty objektů nedávají smysl (počet obyvatel, cena), pošlete místo něj souhrnný vývoj v dm.chart – portál ho u posuvníku ukáže jako čárový graf, viz vývoj v čase a trend. Bez obojího 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.

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": "society",
    "keywords": ["obyvatelé", "vývoj", "trend", "růst", "vylidňování"],
    "useCases": ["housing", "public-administration"],
    "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)

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": […] }
}

{
  "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 } }
    ]
  }
}

Souhrnný vývoj za celé území místo počtů objektů (zvolené období 2023–2025):

{
  "type": "FeatureCollection",
  "features": [],
  "dm": {
    "chart": {
      "label": "Počet obyvatel Česka k 31. 12.",
      "highlight": { "from": "2022", "to": "2025" },
      "points": [
        { "period": "2021", "value": 10516707 },
        { "period": "2022", "value": 10827529 },
        { "period": "2023", "value": 10900555 },
        { "period": "2024", "value": 10909500 },
        { "period": "2025", "value": 10915839 }
      ]
    }
  }
}

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 }
        ]
      }
    }
  }]
}

Cache

Validace

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

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