DatovaMapa.sk

Strojovo čitateľná verzia: /dokumentacia/protokol.md

Protokol DátovejMapy 0.1

Normatívny popis rozhrania medzi poskytovateľom dát a portálom. Pri rozpore s inou dokumentáciou platí tento dokument a strojové schémy:

Postup prípravy dát krok za krokom (najmä pre AI agentov) je v návode pre AI agentov, zrozumiteľný úvod v sprievodcovi pre poskytovateľov. Platné vzory: manifest-complete.json, data-points.json.

Prehľad

Poskytovateľ                         Portál DátovaMapa                 Prehliadač
─────────────                        ─────────────────                 ─────────
manifest.json  ◄── GET (cache 10 min) ── register → katalóg ─────────► /api/catalog
data endpoint  ◄── GET ?bbox&zoom&… ──── proxy + validácia + cache ───► /api/data/{provider}/{dataset}
rastrové dlaždice ◄───────────────────────────────────────────────────── priamo z prehliadača

Všeobecné pravidlá

Manifest

Pole Povinné Popis
protocol áno Verzia protokolu, napr. "0.1"
provider.id áno Identifikátor; musí zodpovedať id v registri portálu
provider.name áno Názov zobrazovaný ako zdroj
provider.description, homepage, logo, contact nie
provider.managedBy nie provider (predvolené) / portal – manifest pre verejnú službu udržiava DátovaMapa
license nie { name, url?, attribution } – predvolená licencia všetkých sád
datasets[] áno 1–200 dátových sád s unikátnym id

Dátová sada

Pole Povinné Popis
id, title áno
description nie
category nie territory, nature, water, risks, energy, transport, society, economy, infrastructure, sample, other; iná hodnota → Ostatné
tags, keywords nie Na vyhľadávanie a budúceho asistenta
useCases nie Účely, pre ktoré sa sada hodí: construction, housing, land-purchase, agriculture, investment…
coverage nie { bbox?, area?, minZoom?, maxZoom? } – pod minZoom portál dáta nenačítava
temporal nie { updated?, frequency?, param? } – param = kľúč parametra, ktorým sa volí obdobie (pozri časový filter)
license nie Prepisuje licenciu poskytovateľa
source áno Odkiaľ brať dáta (pozri nižšie)
presentation áno Ako dáta vykresliť (pozri nižšie)
fields[] nie Popis vlastností objektov: key, label, type, unit, decimals, description, primary
params[] nie Filtre pre používateľa (pozri nižšie)
cache nie { ttl?: sekundy, store?: boolean }

source

geojson – natívny formát.

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

raster – hotové dlaždice, prehliadač ich načítava priamo zo zdroja.

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

Šablóny podporujú {z}/{x}/{y} aj {bbox-epsg-3857} (WMS GetMap). Len https.

presentation

type Geometria Voľby
circle body color, radius, opacity, strokeColor, strokeWidth, label, cluster
heatmap body weight, radius, intensity, colors[], opacity
line línie color, width, opacity, dash[], label
fill plochy color, opacity, outlineColor, outlineWidth, label
raster dlaždice opacity
auto čokoľvek color

Všetky typy majú voliteľnú legend: [{ label, color }] (max. 20 položiek). Portál ju ukazuje v legende priamo v mape a vo výbere vrstiev. Pri vektorových typoch ju vie odvodiť z farieb, pri raster nie – farby sú zapečené v obrázkoch dlaždíc, takže legendu rastra uveďte ručne (napr. prevzatím z legendy WMS / ArcGIS služby).

Farba (color) je buď hex reťazec, alebo pravidlo podľa vlastnosti objektu:

{ "field": "druh", "type": "categorical", "values": { "papier": "#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 farbí objekty podľa toho, či ich hodnota v čase rastie, stagnuje, alebo klesá. Počíta ho portál z grafu vývoja dm.chart – pozri vývoj v čase a trend.

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

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

params

Filter, ktorý používateľ nastaví v portáli; portál ho pošle ako query parameter key=value.

type Hodnota v dopyte
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 znakov)

Kľúče bbox, zoom, limit, cursor, lang, protocol sú rezervované. Portál posiela len deklarované parametre a hodnoty vopred overí; nevyplnený parameter nahradí default.

Časový filter

Dáta v čase (nehody, merania, udalosti) majú jeden parameter pre obdobie a odkazujú naň z temporal.param. Portál ho potom neukazuje medzi ostatnými filtrami, ale ako časovú os v okne pod legendou: posuvník obdobia a stĺpcový graf po rokoch, v ktorom sa dá obdobie vybrať kliknutím alebo ťahaním. Zvolené obdobie je vidieť aj pri vrstve v legende.

{
  "protocol": "0.1",
  "provider": { "id": "mesto-priklad", "name": "Mesto Príklad" },
  "license": { "name": "CC BY 4.0", "attribution": "© Mesto Príklad" },
  "datasets": [{
    "id": "nehody",
    "title": "Dopravné nehody",
    "description": "Nehody evidované políciou podľa následkov.",
    "category": "transport",
    "keywords": ["nehoda", "dopravná nehoda", "bezpečnosť", "zranenie", "križovatka"],
    "useCases": ["transport", "housing"],
    "coverage": { "bbox": [21.15, 48.65, 21.35, 48.78], "minZoom": 12 },
    "temporal": { "frequency": "ročne", "param": "obdobi" },
    "source": { "type": "geojson", "url": "https://data.mesto-priklad.sk/datovamapa/nehody", "mode": "bbox", "maxFeatures": 5000 },
    "presentation": {
      "type": "circle",
      "color": { "field": "nasledky", "type": "categorical", "values": { "zranenie": "#dc2626", "hmotná škoda": "#facc15" }, "default": "#facc15" }
    },
    "fields": [
      { "key": "nasledky", "label": "Následky", "type": "string", "primary": true },
      { "key": "datum", "label": "Dátum", "type": "date" }
    ],
    "params": [{ "key": "obdobi", "label": "Obdobie", "type": "range", "min": 2015, "max": 2025, "step": 1, "default": "2025,2025" }]
  }]
}

Graf kreslí portál z dm.timeline v odpovedi (pozri dátová odpoveď). Pri hodnotách v čase, kde počty objektov nedávajú zmysel (počet obyvateľov, cena), pošlite namiesto neho súhrnný vývoj v dm.chart – portál ho pri posuvníku ukáže ako čiarový graf, pozri vývoj v čase a trend. Bez oboch ostane len posuvník obdobia.

Vývoj v čase a trend

Štandardné zobrazenie dát, ktorých hodnota sa pri objekte mení v čase – počet obyvateľov obce, cena, nameraná koncentrácia, návštevnosť. Kedykoľvek majú dáta takýto rad, posielajte ho; portál z neho sám kreslí graf a vie podľa neho farbiť.

Trend vychádza z relatívnej zmeny, hodí sa preto pre kladné veličiny (počty, ceny, koncentrácie). Hodnoty okolo nuly, ako saldo sťahovania, farbite cez interpolate a vývoj ukážte len grafom.

{
  "protocol": "0.1",
  "provider": { "id": "kraj-priklad", "name": "Kraj Príklad" },
  "license": { "name": "CC BY 4.0", "attribution": "© Kraj Príklad" },
  "datasets": [{
    "id": "vyvoj-obyvatel",
    "title": "Vývoj počtu obyvateľov obcí",
    "description": "Kde obyvateľov pribúda a kde ubúda. Farba podľa trendu vo zvolenom období, v detaile obce graf po rokoch.",
    "category": "society",
    "keywords": ["obyvatelia", "vývoj", "trend", "rast", "vyľudňovanie"],
    "useCases": ["housing", "public-administration"],
    "temporal": { "frequency": "ročne", "param": "obdobi" },
    "source": { "type": "geojson", "url": "https://data.kraj-priklad.sk/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": "Obyvateľov na konci obdobia", "type": "integer" }
    ],
    "params": [{ "key": "obdobi", "label": "Obdobie", "type": "range", "min": 2015, "max": 2025, "step": 1, "default": "2015,2025" }]
  }]
}

Odpoveď potom pri každej obci posiela rad za všetky roky a zvolené obdobie v highlight, napríklad { "from": "2015", "to": "2025" }.

Dátový dopyt

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

Dátová odpoveď

GeoJSON FeatureCollection (RFC 7946). Podporované geometrie: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon. Objekty s geometry: null sa preskočia.

Voliteľné rozšírenia:

{
  "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": { "zranenie": 701, "hmotná škoda": 1665 } },
      { "period": "2025", "count": 1894, "values": { "zranenie": 652, "hmotná škoda": 1242 } }
    ]
  }
}

Súhrnný vývoj za celé územie namiesto počtov objektov (zvolené obdobie 2023–2025):

{
  "type": "FeatureCollection",
  "features": [],
  "dm": {
    "chart": {
      "label": "Počet obyvateľov Slovenska k 31. 12.",
      "highlight": { "from": "2022", "to": "2025" },
      "points": [
        { "period": "2021", "value": 5459781 },
        { "period": "2022", "value": 5434712 },
        { "period": "2023", "value": 5424687 },
        { "period": "2024", "value": 5415949 },
        { "period": "2025", "value": 5410836 }
      ]
    }
  }
}

Objekt s grafom vývoja v detaile:

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "id": "500496",
    "geometry": { "type": "Point", "coordinates": [18.7408, 49.2231] },
    "properties": { "nazev": "Žilina", "obyvatel": 80500 },
    "dm": {
      "chart": {
        "label": "Počet obyvateľov k 31. 12.",
        "points": [
          { "period": "2023", "value": 81200 },
          { "period": "2024", "value": 80900 },
          { "period": "2025", "value": 80500 }
        ]
      }
    }
  }]
}

Cache

Validácia

Zhodu s protokolom overuje validátor (POST /api/validate, živý test GET /api/validate?manifestUrl=…, alebo MCP nástroje validate_manifest a validate_data). Rozlišuje:

Každý nález má stabilný code (prehľad kódov), cestu path a pri odporúčaniach radu hint. Kódy sa medzi minor verziami nemenia, nové môžu pribúdať.

Vývoj protokolu