API portálu DatováMapa

Strojové rozhraní portálu pro aplikace a AI agenty: katalog dat, data ze všech zdrojů ve sjednoceném tvaru, dotazy na místo (co je v bodě a okolí, souhrn za obec), validátor a registrace pro poskytovatele a MCP server. Vše je veřejné, bez autentizace, s CORS *. Formální popis je v OpenAPI.

Přehled

Katalog

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

Katalog obsahuje jen schválená data. Sady poskytovatelů, kteří se zaregistrovali sami a zatím nejsou schválení, v něm nejsou (viz Registrace).

Datové sady nesou všechna pole z manifestu poskytovatele (description, fields, params, coverage…) kromě URL zdroje – GeoJSON data se čtou přes portál (links.data), rastrové dlaždice přímo ze zdroje (source.tiles). Stejný obsah čitelný pro lidi i modely: zdroje.md.

Data

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

Odpověď je GeoJSON FeatureCollection. Údaje z feature.dm poskytovatele jsou přesunuté do properties s prefixem __dm_ (__dm_title, __dm_description, __dm_url, __dm_color, __dm_chart). U sad s color.type = "trend" přidá portál __dm_trend (roste, stagnuje, klesá) spočítaný z dm.chart. Metadata odpovědi:

{ "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 (čerstvě ze zdroje), stale (zdroj nedostupný, poslední známá data – viz dm.notice).

Chyby mají tvar { "error": "zpráva", "code": "kod" }: 400 neplatný dotaz, 404 neznámá sada, 502 chyba zdroje.

Sady jen k zobrazení. U několika sad spravovaných portálem nemá zdroj doloženou licenci k dalšímu šíření. Portál je kreslí ve vlastní mapě, ale data dál nevydává: v katalogu mají links.data prázdné a v links.source adresu původní služby poskytovatele. Dotaz mimo mapu portálu dostane 303 s hlavičkou Location na tuto službu a tělem { "error": "…", "code": "display_only", "source": "…" }. Stejně odpoví nástroj MCP fetch_data.

Místo a okolí

Dotazy pro AI asistenty a aplikace, které odpovídají na otázky o konkrétním místě. Vrací lidsky popsané hodnoty (popisky a jednotky podle fields sady) bez geometrií, s atribucí a odkazem na mapu. Návod pro uživatele asistentů: Data pro AI asistenty.

Hledání místa

GET /api/places?query=Thámova 7, Praha (volitelně max, výchozí 5, nejvýš 10)

Hledá v registru adres RÚIAN (© ČÚZK, CC BY 4.0) adresy, ulice, obce, části obcí a další územní prvky. Zadejte jen adresu nebo název; upřesnění jako okres nebo „u Zlína“ služba nezná. municipality je obec, ve které místo leží (name, district, region a kód obce ČSÚ code) – pro ni umí souhrn data za celou obec. U míst mimo města nad 10 000 obyvatel je navíc near nejbližší takové město a vzdálenost v km; podle obojího se rozliší stejnojmenná místa.

{
  "query": "Thámova 7, Praha",
  "count": 1,
  "places": [{ "name": "Thámova 221/7, Karlín, 18600 Praha 8", "type": "adresa", "point": [14.452653, 50.091436], "municipality": { "slug": "praha", "code": "554782", "name": "Praha", "district": "Praha", "region": "Hlavní město Praha" } }],
  "attribution": "© ČÚZK, RÚIAN (CC BY 4.0)"
}

Co je v bodě a okolí

GET /api/nearby

Jedno z datasets, purpose, search je povinné. Automatický výběr bere jen sady, které na bod umí odpovědět: nejdřív rizika a omezení, podkladové mapy nakonec. Sady nad limit vrátí v skipped.

• GeoJSON sady: objekty do vzdálenosti radius seřazené od nejbližšího. distance je v metrech, 0 = bod leží uvnitř plochy (např. obec u kartogramu). count je počet objektů v okolí. Sady, které se načítají jen při velkém přiblížení, okolí zmenší (radius, notice). U celých sad (mode: full), které v okolí nic nemají, vrátí aspoň nejbližší objekt (např. měřicí stanici).
• Rastrové sady: portál se zeptá zdroje přímo na bod. Dotaz odvodí ze šablony dlaždic: WMS GetMap → GetFeatureInfo, ArcGIS MapServer/export → identify, ImageServer/exportImage → identify s tabulkou tříd rastru. Hodnoty jsou atributy zdroje (názvy polí, jak je zdroj vrací). K výkladu kódů pomůže description a legend.

{
  "place": { "name": "Thámova 221/7, Karlín, 18600 Praha 8", "type": "adresa", "point": [14.452653, 50.091436] },
  "point": [14.452653, 50.091436],
  "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.cz/?d=cgs/radon&d=npu/kulturni-pamatky#15/50.09144/14.45265"
}

Souhrn

GET /api/summary/{provider}/{dataset}?municipality=Ostrava (ostatní query parametry jsou parametry sady)

Souhrn GeoJSON sady za celé území, nebo s municipality jen za obec – kteroukoli obec Česka: count, categories (počty podle kategorie barvy), rankings (nejvyšší a nejnižší hodnoty) a u kartogramu own – hodnoty plochy, ve které obec leží. Jsou to stejná čísla, jaká ukazuje stránka sady. Sady načítané jen při velkém přiblížení mají souhrn jen za obec. Rastrové sady souhrn nemají.

municipality je název („Ostrava“), název s okresem nebo krajem („Nová Ves (okres Mělník)“), kód obce ČSÚ („535117“, vrací ho hledání místa v municipality.code) nebo adresa jejího přehledu („stredocesky-kraj/nova-ves-melnik“). Samotný název, který nese víc obcí, skončí chybou ambiguous_place se seznamem těchto obcí, jejich okresů a kódů.

Validátor

Nástroj pro poskytovatele a jejich AI agenty. Vrací 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 tělem:
  • manifest (objekt s datasets) nebo { "manifest": … } – statická kontrola,
  • GeoJSON FeatureCollection nebo { "data": …, "dataset": … } – kontrola dat; s dataset (objekt sady z manifestu) i soulad s manifestem,
  • { "manifestUrl": "https://…" } – živý test.
• GET /api/validate?manifestUrl=https://… – živý test: stáhne manifest, zkontroluje ho a na každou sadu pošle testovací dotaz jako portál (u bbox na střed coverage.bbox, zoom 12 nebo coverage.minZoom; u rastru jednu dlaždici). Report má navíc provider a datasets[] s request, durationMs, featureCount, errors, warnings.

Registrace

POST /api/registration s tělem { "manifestUrl": "https://…" }. Portál manifest zkontroluje živým testem (jako validátor). Když projde, zaregistruje poskytovatele mezi neschválená data:

• Data jsou dostupná přes /api/data/… i na stránkách sad /mapa/{provider}/{dataset}. Stránka nejdřív ukáže varování, že data nahrála třetí strana a provozovatel je neschválil. Data do mapy načte až po potvrzení. Stránka má noindex.
• Do katalogu, vyhledávání, llms.txt, MCP nástroje catalog a na stránky za obce se data dostanou až po schválení provozovatelem.
• Schválení platí pro otisk (SHA-256) obsahu manifestu. Po změně manifestu je poskytovatel zase neschválený, dokud ho provozovatel neschválí znovu.
• Přehled neschválených poskytovatelů: /neschvalena-data.

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

MCP server

Endpoint https://datovamapa.cz/mcp, transport Streamable HTTP (bezstavový, odpovědi JSON), bez autentizace.

Připojení:

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

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

Odkaz na mapu

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

Každá sada má i vlastní stránku s mapou a popisem: https://datovamapa.cz/mapa/{provider}/{dataset}, celostátní GeoJSON sady také za obce nad 10 000 obyvatel: https://datovamapa.cz/mapa/{provider}/{dataset}/{obec} (např. /mapa/chmu/kvalita-ovzdusi/ostrava). Odkaz na stránku sady je v katalogu v links.map. Na stránce sady (i sestavené mapy /mapy/{slug}) se do ?d=… zapisuje jen rozdíl proti výchozímu výběru: bez d platí sady stránky, d vyjmenuje celý výběr (?d= = nic zapnuto) a parametr se uvádí, jen když se liší od výchozího.

Příklad – dopravní nehody v Brně souhrnně za roky 2019–2023: /?d=brno/dopravni-nehody&brno/dopravni-nehody.obdobi=2019,2023#13/49.195/16.608

Kódy nálezů

Stabilní kódy chyb (errors) a doporučení (warnings) validátoru a proxy.

Manifest

Data

Živý test a proxy