DatovaMapa.cz

Strojově čitelná verze: /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 }
live ne { interval: sekundy } – živá data: otevřená mapa sadu sama obnovuje (10 až 3600 s), viz cache
detail ne { url } – detail objektu na vyžádání po kliknutí (jízdní řád, bohatší popis, zvýraznění v mapě), viz detail objektu
profile ne Druh sady se společným chováním v portálu: transit_vehicles = živé polohy vozidel veřejné dopravy, viz doprava

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.

image – jeden georeferencovaný obrázek přes celé území (radar, družicový snímek, předpovědní mapa), nebo řada snímků v čase. Prohlížeč ho načítá přes portál (/api/image/…), zdroj tedy nemusí posílat hlavičky CORS.

{ "type": "image", "frames": "radar.json", "coordinates": [[11.267, 51.458], [19.624, 51.458], [19.624, 48.047], [11.267, 48.047]] }

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, obrázek 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 }
        ]
      }
    }
  }]
}

Detail objektu

Sada může nabídnout detail objektu na vyžádání: po kliknutí na objekt portál ukáže popup z vlastností a pod ním doplní detail, který se stáhne zvlášť. Hodí se pro bohatší obsah, který se nevejde do vlastností: jízdní řád vlaku, průběh jízdy, zvýraznění trasy v mapě. Pole detail v sadě obsahuje šablonu adresy se zástupným {id}, za které portál dosadí id objektu z dat (objekty proto musí mít stabilní id). Adresa je https, nebo relativní vůči manifestu; validátor hlásí šablonu bez {id} (detail_url_without_id) a jiné schéma než https (detail_url_not_https).

"detail": { "url": "https://data.example.cz/detail?id={id}" }

Odpověď je JSON FeatureDetail (title a generated jsou povinné, ostatní pole volitelná):

Dokud je detail otevřený, mapa ho obnovuje s intervalem live.interval sady. Portál odpovědi cachuje podle ttl a jejich schéma ověřuje stejně jako data. Neznámé id vrací poskytovatel jako 404.

{
  "title": "RJ 1000",
  "subtitle": "→ Praha-Zahradní Město · RegioJet a.s.",
  "badge": {
    "text": "RJ 1000",
    "color": "#0f766e"
  },
  "status": {
    "label": "+8 min",
    "tone": "warning"
  },
  "journey": {
    "calls": [
      {
        "name": "Ostrava hlavní nádraží",
        "departure": "2026-11-04T05:05:00+01:00",
        "scheduledDeparture": "2026-11-04T05:05:00+01:00",
        "platform": "2",
        "state": "passed"
      },
      {
        "name": "Pardubice hlavní nádraží",
        "arrival": "2026-11-04T07:30:00+01:00",
        "departure": "2026-11-04T07:38:00+01:00",
        "scheduledArrival": "2026-11-04T07:22:00+01:00",
        "scheduledDeparture": "2026-11-04T07:30:00+01:00",
        "platform": "3",
        "state": "current"
      }
    ]
  },
  "highlight": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "LineString",
          "coordinates": [
            [
              15.77,
              50.03
            ],
            [
              14.43,
              50.08
            ],
            [
              14.6,
              50.07
            ]
          ]
        },
        "properties": {
          "role": "upcoming"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            15.77,
            50.03
          ]
        },
        "properties": {
          "role": "current",
          "name": "Pardubice hlavní nádraží"
        }
      }
    ]
  },
  "color": "#0f766e",
  "generated": "2026-11-04T07:35:00Z",
  "ttl": 30
}

Úplný příklad: detail-jizda.json.

Doprava

Sady s živými polohami vozidel veřejné dopravy (vlaky, autobusy, tramvaje, metro…) označte "profile": "transit_vehicles". Portál je pak ukáže ve společné vrstvě „Doprava živě“: všechny stejným stylem (tvar podle druhu, barva podle zpoždění), s jednou legendou, filtrem podle druhu dopravy, zpoždění a dopravce a s hledáním spoje. Uživatel tak vybírá druh dopravy, ne zdroj dat.

Sada s profilem musí mít live, prezentaci circle a objekty jako body s feature.dm.transit. Validátor hlásí chybějící live (transit_missing_live), jinou prezentaci (transit_not_circle), objekt bez dm.transit (transit_missing_properties) a objekt, který není bod (transit_not_point).

Pole dm.transit Povinné Popis
mode ano rail, bus, tram, metro, trolleybus, ferry, funicular, other
label ano Označení, které lidé hledají: vlak (R 1234), linka (188)
line ne Linka, když se liší od označení (S2)
headsign, operator ne Cíl spoje, dopravce
delay_min ne Zpoždění v celých minutách, záporné = před časem
delay_band ano on_time do 4 min, minor 5 až 14, medium 15 až 29, major 30 až 59, extreme 60 a víc, unknown bez údaje
bearing ne Směr jízdy ve stupních od severu
trip_ref ne Stálý klíč spoje (stejný napříč obnovami); stejný jako id objektu, pokud sada nabízí detail jízdy
observed_at ano Kdy byla poloha změřena (ISO 8601)

Každé vozidlo má být na mapě jen jednou. Když stejná vozidla hlásí víc zdrojů, ať je vydává jen jedna sada. Vlastnosti v properties (popisky pro lidi v jazyce země) zůstávají, dm.transit je neutrální část pro portál.

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "id": "1234|20261104",
    "geometry": { "type": "Point", "coordinates": [14.4352, 50.0833] },
    "properties": { "vlak": "R 1234", "cil": "Brno hl.n.", "zpozdeni_min": 6 },
    "dm": {
      "transit": {
        "mode": "rail", "label": "R 1234", "headsign": "Brno hl.n.", "operator": "České dráhy",
        "delay_min": 6, "delay_band": "minor", "bearing": 135, "trip_ref": "1234|20261104",
        "observed_at": "2026-11-04T07:35:10Z"
      }
    }
  }]
}

Úplný příklad: data-doprava.json.

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