API portálu DátováMapa

Strojové rozhranie portálu pre aplikácie a AI agentov: katalóg dát, dáta zo všetkých zdrojov v zjednotenom tvare, dotazy na miesto (čo je v bode a okolí, súhrn za obec), validátor a registrácia pre poskytovateľov a MCP server. Všetko je verejné, bez autentifikácie, s CORS *. Formálny popis je v OpenAPI.

Prehľad

Katalóg

GET /api/catalog

{
  "protocol": "0.1",
  "generated": "2026-10-06T08:00:00.000Z",
  "providers": [{ "id": "cgs", "name": "Česká geologická služba", "status": "ok", "datasetCount": 2, "managedBy": "portal" }],
  "datasets": [
    {
      "key": "cgs/radon",
      "providerId": "cgs",
      "providerName": "Česká geologická služba",
      "title": "Radonový index",
      "category": "risks",
      "categoryLabel": "Rizika a omezení",
      "keywords": ["radon"],
      "useCases": ["construction", "housing"],
      "source": { "type": "raster", "tiles": ["https://…"] },
      "presentation": { "type": "raster", "opacity": 0.45 },
      "attribution": "© Česká geologická služba",
      "links": { "data": null, "map": "/?d=cgs/radon" }
    }
  ]
}

Katalóg obsahuje iba schválené dáta. Sady poskytovateľov, ktorí sa zaregistrovali sami a zatiaľ nie sú schválení, v ňom nie sú (pozri Registrácia).

Dátové sady nesú všetky polia z manifestu poskytovateľa (description, fields, params, coverage…) okrem URL zdroja – GeoJSON dáta sa čítajú cez portál (links.data), rastrové dlaždice priamo zo zdroja (source.tiles). Rovnaký obsah čitateľný pre ľudí aj modely: zdroje.md.

Dáta

GET /api/data/{provider}/{dataset}

Odpoveď je GeoJSON FeatureCollection. Údaje z feature.dm poskytovateľa sú presunuté do properties s prefixom __dm_ (__dm_title, __dm_description, __dm_url, __dm_color, __dm_chart). Pri sadách s color.type = "trend" pridá portál __dm_trend (roste, stagnuje, klesá) vypočítaný z dm.chart. Metadáta odpovede:

{ "dm": { "protocol": "0.1", "dataset": "aopk/pamatne-stromy", "generated": "…", "ttl": 86400, "total": 13, "truncated": false, "notice": null } }

Hlavička X-DM-Cache: hit (z cache), miss (čerstvo zo zdroja), stale (zdroj nedostupný, posledné známe dáta – pozri dm.notice).

Chyby majú tvar { "error": "správa", "code": "kod" }: 400 neplatný dotaz, 404 neznáma sada, 502 chyba zdroja.

Sady len na zobrazenie. Pri niekoľkých sadách spravovaných portálom nemá zdroj doloženú licenciu na ďalšie šírenie. Portál ich kreslí vo vlastnej mape, ale dáta ďalej nevydáva: v katalógu majú links.data prázdne a v links.source adresu pôvodnej služby poskytovateľa. Dotaz mimo mapu portálu dostane 303 s hlavičkou Location na túto službu a telom { "error": "…", "code": "display_only", "source": "…" }. Rovnako odpovie nástroj MCP fetch_data.

Miesto a okolie

Dotazy pre AI asistentov a aplikácie, ktoré odpovedajú na otázky o konkrétnom mieste. Vracajú ľudsky popísané hodnoty (popisky a jednotky podľa fields sady) bez geometrií, s atribúciou a odkazom na mapu. Návod pre používateľov asistentov: Dáta pre AI asistentov.

Hľadanie miesta

GET /api/places?query=Hlavná 1, Košice (voliteľne max, predvolene 5, najviac 10)

Hľadá v registri adries adresy, ulice, obce, časti obcí a ďalšie územné prvky. Zadajte len adresu alebo názov; upresnenia ako okres alebo „pri Zlatých Moravciach“ služba nepozná. municipality je obec, v ktorej miesto leží (name, district, region a kód obce code) – pre ňu vie súhrn dáta za celú obec. Pri miestach mimo miest nad 10 000 obyvateľov je navyše near najbližšie takéto mesto a vzdialenosť v km; podľa oboch sa rozlíšia rovnomenné miesta.

{
  "query": "Hlavná 1, Košice",
  "count": 1,
  "places": [{ "name": "Hlavná 1, 04001 Košice", "type": "adresa", "point": [21.258, 48.7209], "municipality": { "slug": "kosice", "code": "598186", "name": "Košice", "district": "Košice I", "region": "Košický kraj" } }],
  "attribution": "© zdroj registra adries"
}

Čo je v bode a okolí

GET /api/nearby

Jedno z datasets, purpose, search je povinné. Automatický výber berie len sady, ktoré vedia na bod odpovedať: najprv riziká a obmedzenia, podkladové mapy nakoniec. Sady nad limit vráti v skipped.

• GeoJSON sady: objekty do vzdialenosti radius zoradené od najbližšieho. distance je v metroch, 0 = bod leží vo vnútri plochy (napr. obec pri kartograme). count je počet objektov v okolí. Sady, ktoré sa načítavajú len pri veľkom priblížení, okolie zmenšia (radius, notice). Pri celých sadách (mode: full), ktoré v okolí nič nemajú, vráti aspoň najbližší objekt (napr. meraciu stanicu).
• Rastrové sady: portál sa opýta zdroja priamo na bod. Dotaz odvodí zo šablóny dlaždíc: WMS GetMap → GetFeatureInfo, ArcGIS MapServer/export → identify, ImageServer/exportImage → identify s tabuľkou tried rastra. Hodnoty sú atribúty zdroja (názvy polí, ako ich zdroj vracia). Pri výklade kódov pomôže description a legend.

{
  "place": { "name": "Hlavná 1, 04001 Košice", "type": "adresa", "point": [21.258, 48.7209] },
  "point": [21.258, 48.7209],
  "radius": 500,
  "generated": "2026-10-06T16:00:00.000Z",
  "results": [
    {
      "dataset": "cgs/radon",
      "title": "Radonový index",
      "provider": "Česká geologická služba",
      "attribution": "© Česká geologická služba",
      "status": "ok",
      "hits": [{ "title": "Radonový index", "distance": 0, "values": [{ "label": "radonovériziko", "value": "přechodný" }, { "label": "stupeňradonovéhoindexu", "value": "2" }] }]
    },
    {
      "dataset": "npu/kulturni-pamatky",
      "title": "Kulturní památky",
      "provider": "Národní památkový ústav",
      "attribution": "Národní památkový ústav",
      "license": "CC BY-SA 4.0",
      "status": "ok",
      "count": 27,
      "radius": 500,
      "hits": [
        {
          "title": "továrna Breitfeld-Daněk",
          "distance": 91,
          "values": [{ "label": "Rejstříkové číslo ÚSKP", "value": "105958" }, { "label": "Stav ochrany", "value": "památkově chráněno" }],
          "url": "https://pamatkovykatalog.cz/x-14624751"
        }
      ]
    }
  ],
  "map": "https://datovamapa.sk/?d=cgs/radon&d=npu/kulturni-pamatky#15/48.7209/21.258"
}

Súhrn

GET /api/summary/{provider}/{dataset}?municipality=Žilina (ostatné query parametre sú parametre sady)

Súhrn GeoJSON sady za celé územie, alebo s municipality len za obec – ktorúkoľvek obec Slovenska: count, categories (počty podľa kategórie farby), rankings (najvyššie a najnižšie hodnoty) a pri kartograme own – hodnoty plochy, v ktorej obec leží. Sú to rovnaké čísla, aké ukazuje stránka sady. Sady načítavané len pri veľkom priblížení majú súhrn len za obec. Rastrové sady súhrn nemajú.

municipality je názov („Žilina“), názov s okresom alebo krajom („Nová Ves (okres Trenčín)“), kód obce („598186“, vracia ho hľadanie miesta v municipality.code) alebo adresa jej prehľadu („trenciansky-kraj/nova-ves-trencin“). Samotný názov, ktorý nesie viac obcí, skončí chybou ambiguous_place so zoznamom týchto obcí, ich okresov a kódov.

Validátor

Nástroj pre poskytovateľov a ich AI agentov. Vracia vždy HTTP 200 a report:

{
  "valid": false,
  "summary": "Manifest není platný: 1 chyb, 2 doporučení.",
  "errors": [{ "path": "datasets[0].source.tiles[0]", "code": "raster_without_template", "message": "Šablona dlaždic neobsahuje {z}/{x}/{y} ani {bbox-epsg-3857}." }],
  "warnings": [{ "path": "datasets[0].keywords", "code": "missing_keywords", "message": "Sada nemá klíčová slova.", "hint": "Doplňte 5–15 slov…" }]
}

• POST /api/validate s telom:
  • manifest (objekt s datasets) alebo { "manifest": … } – statická kontrola,
  • GeoJSON FeatureCollection alebo { "data": …, "dataset": … } – kontrola dát; s dataset (objekt sady z manifestu) aj súlad s manifestom,
  • { "manifestUrl": "https://…" } – živý test.
• GET /api/validate?manifestUrl=https://… – živý test: stiahne manifest, skontroluje ho a na každú sadu pošle testovací dotaz ako portál (pri bbox na stred coverage.bbox, zoom 12 alebo coverage.minZoom; pri rastri jednu dlaždicu). Report má navyše provider a datasets[] s request, durationMs, featureCount, errors, warnings.

Registrácia

POST /api/registration s telom { "manifestUrl": "https://…" }. Portál manifest skontroluje živým testom (ako validátor). Keď prejde, zaregistruje poskytovateľa medzi neschválené dáta:

• Dáta sú dostupné cez /api/data/… aj na stránkach sád /mapa/{provider}/{dataset}. Stránka najprv ukáže varovanie, že dáta nahrala tretia strana a prevádzkovateľ ich neschválil. Dáta do mapy načíta až po potvrdení. Stránka má noindex.
• Do katalógu, vyhľadávania, llms.txt, MCP nástroja catalog a na stránky za obce sa dáta dostanú až po schválení prevádzkovateľom.
• Schválenie platí pre odtlačok (SHA-256) obsahu manifestu. Po zmene manifestu je poskytovateľ opäť neschválený, kým ho prevádzkovateľ neschváli znova.
• Prehľad neschválených poskytovateľov: /neschvalene-data.

{
  "registered": true,
  "status": "pending_review",
  "message": "Registrováno. …",
  "provider": { "id": "obec-priklad", "name": "Obec Příklad" },
  "links": { "review": "/neschvalene-data#obec-priklad", "datasets": ["/mapa/obec-priklad/lavicky"] },
  "check": { "summary": "Poskytovatel je platný bez výhrad.", "warnings": [] }
}

MCP server

Endpoint https://datovamapa.sk/mcp, transport Streamable HTTP (bezstavový, odpovede JSON), bez autentifikácie.

Pripojenie:

claude mcp add --transport http datovamapa https://datovamapa.sk/mcp

{ "mcpServers": { "datovamapa": { "type": "http", "url": "https://datovamapa.sk/mcp" } } }

Odkaz na mapu

https://datovamapa.sk/?d={provider}/{dataset}&d=…&{provider}/{dataset}.{param}={hodnota}#{zoom}/{lat}/{lon}

Každá sada má aj vlastnú stránku s mapou a popisom: https://datovamapa.sk/mapa/{provider}/{dataset}, celoštátne GeoJSON sady aj za obce nad 10 000 obyvateľov: https://datovamapa.sk/mapa/{provider}/{dataset}/{obec} (napr. /mapa/chmu/kvalita-ovzdusi/ostrava). Odkaz na stránku sady je v katalógu v links.map. Na stránke sady (aj zostavenej mapy /mapy/{slug}) sa do ?d=… zapisuje len rozdiel oproti predvolenému výberu: bez d platia sady stránky, d vymenuje celý výber (?d= = nič nie je zapnuté) a parameter sa uvádza, len keď sa líši od predvoleného.

Príklad – dopravné nehody v Brne súhrnne za roky 2019–2023: /?d=brno/dopravni-nehody&brno/dopravni-nehody.obdobi=2019,2023#13/49.195/16.608

Kódy nálezov

Stabilné kódy chýb (errors) a odporúčaní (warnings) validátora a proxy.

Manifest

Dáta

Živý test a proxy