DatovaMapa.sk

Strojovo čitateľná verzia: /dokumentacia/pre-poskytovatelov.md

Pripojte svoje dáta do DátovejMapy

DátováMapa je otvorený portál, ktorý zobrazuje dáta z mnohých zdrojov v jednej mape. Nemusíte riešiť mapu, štýly ani mapový server. Stačí zverejniť manifest (popis vašich dát) a dáta ako GeoJSON. Portál sa na dáta spýta v okamihu, keď ich používateľ zapne, vykreslí ich podľa vášho popisu a uvedie vás ako zdroj.

Pripravuje dáta AI agent? Dajte mu odkaz na návod pre AI agentov. Obsahuje postup krok za krokom, šablóny kódu a kritériá hotovej práce. Celá dokumentácia je strojovo čitateľná: llms.txt, MCP server, validátor.

Tri spôsoby pripojenia

Spôsob Kedy Čo potrebujete
Statické súbory do zhruba 2 000 objektov, dáta sa menia občas manifest.json + data.geojson na ľubovoľnom webe (aj GitHub Pages)
Vlastný endpoint veľké alebo živé sady HTTP GET endpoint, ktorý filtruje podľa výrezu mapy (bbox)
Existujúce WMS / dlaždice máte mapový server iba manifest so zdrojom typu raster

1. Manifest

Jeden JSON, ktorý popisuje vás a vaše dátové sady. Povinné je len minimum: protocol, provider.id, provider.name a pri každej sade id, title, source a presentation. Všetko ostatné je voliteľné, ale pomáha ľuďom aj AI asistentovi portálu dáta nájsť a pochopiť (description, keywords, useCases, fields).

Najmenší rozumný manifest (statické súbory, relatívna URL sa počíta od adresy manifestu):

{
  "protocol": "0.1",
  "provider": { "id": "obec-priklad", "name": "Obec Príklad", "homepage": "https://www.obec-priklad.sk/" },
  "license": { "name": "CC BY 4.0", "attribution": "© Obec Príklad" },
  "datasets": [
    {
      "id": "lavicky",
      "title": "Lavičky v obci",
      "description": "Verejné lavičky udržiavané obcou.",
      "category": "society",
      "keywords": ["lavička", "posedenie", "odpočinok", "park"],
      "useCases": ["tourism"],
      "source": { "type": "geojson", "url": "lavicky.geojson", "mode": "full" },
      "presentation": { "type": "circle", "color": "#0d9488" },
      "fields": [{ "key": "umisteni", "label": "Umiestnenie", "primary": true }]
    }
  ]
}

Úplný príklad so všetkými možnosťami (filtre, farby podľa hodnôt, zoskupovanie, kartogram, WMS): manifest-complete.json.

2. Dáta

Odpoveďou je GeoJSON FeatureCollection so súradnicami vo WGS84 v poradí [lon, lat]. Člen dm je voliteľný: nadpis a odkaz pri objekte, celkový počet objektov, platnosť odpovede.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1842,
      "geometry": { "type": "Point", "coordinates": [21.2611, 48.7164] },
      "properties": { "druh": "papier", "vyvoz": "2026-10-01" },
      "dm": { "title": "Kontajner Hlavná ulica", "url": "https://www.mesto-priklad.sk/odpady/1842" }
    }
  ],
  "dm": { "total": 1, "ttl": 3600 }
}

Ako sa portál pýta

Režim full – celá sada jedným dopytom. Režim bbox – portál pošle výrez mapy zarovnaný na dlaždice a úroveň priblíženia, plus filtre nastavené používateľom:

GET https://data.mesto-priklad.sk/datovamapa/kontejnery?bbox=21.093750,48.690960,21.269531,48.806863&zoom=11&limit=5000&lang=sk&protocol=0.1&druh=papier,plast
Accept: application/geo+json, application/json
User-Agent: DatovaMapa/0.1 (+https://datovamapa.sk/dokumentacia/pre-poskytovatelov)

Vráťte najviac limit objektov (max. 5 000). Pri veľkých sadách nastavte coverage.minZoom, alebo pri malom priblížení vracajte agregované dáta.

3. Vizualizácia

presentation.type Geometria Typické použitie
circle body miesta, farba podľa kategórie, veľkosť podľa hodnoty, zoskupovanie
heatmap body hustota výskytu, voliteľne vážená hodnotou
line línie trasy, siete, toky
fill plochy územia, kartogram podľa hodnoty
raster dlaždice hotové mapové vrstvy (WMS, XYZ); legendu uveďte v legend
auto čokoľvek predvolené vykreslenie

Farby sú vždy v hex zápise. Farba môže závisieť od vlastnosti objektu – podľa kategórie (categorical), plynulo (interpolate) alebo po intervaloch (step). Podrobnosti v protokole. Ďalšie typy budeme pridávať; typ, ktorý portál nepozná, vykreslí ako auto.

Dáta, ktorých hodnota sa mení v čase (počet obyvateľov, ceny, merania), majú v štandarde vlastné zobrazenie: pri každom objekte pošlite rad hodnôt v dm.chart a portál ho ukáže ako graf v detaile. Ak ide hlavne o to, či hodnota rastie, alebo klesá, nastavte color: { "type": "trend" } – portál z grafu sám zafarbí objekty na zeleno, sivo a červeno a doplní legendu. Podrobnosti v protokole.

4. Overenie

Skôr než manifest pošlete, nechajte ho skontrolovať validátorom. Vracia chyby aj odporúčania so stabilnými kódmi a radami, ako ich opraviť:

curl -X POST https://datovamapa.sk/api/validate -H 'Content-Type: application/json' --data @manifest.json
curl 'https://datovamapa.sk/api/validate?manifestUrl=https://data.mesto-priklad.sk/datovamapa/manifest.json'

Druhý príkaz urobí živý test: stiahne manifest a na každú sadu pošle rovnaký dopyt, aký by poslal portál.

5. Registrácia

Keď validátor hlási "valid": true, zaregistrujte URL manifestu na datovamapa.sk/registracia, cez API alebo MCP nástroj register_provider:

curl -X POST https://datovamapa.sk/api/registration -H 'Content-Type: application/json' --data '{"manifestUrl": "https://data.mesto-priklad.sk/datovamapa/manifest.json"}'

Portál manifest znova skontroluje živým testom. Potom platí:

Registráciou potvrdzujete, že dáta smiete zverejniť pod uvedenou licenciou a že neobsahujú osobné údaje. Prevádzkovateľ môže registráciu kedykoľvek zamietnuť; dáta potom z portálu zmiznú.

Cache a podmienky

Odkazy