DatovaMapa.cz

Strojově čitelná verze: /dokumentace/pro-poskytovatele.md

Připojte svá data do DatovéMapy

DatováMapa je otevřený portál, který zobrazuje data z mnoha zdrojů v jedné mapě. Nemusíte řešit mapu, styly ani mapový server. Stačí zveřejnit manifest (popis vašich dat) a data jako GeoJSON. Portál se na data zeptá ve chvíli, kdy je uživatel zapne, vykreslí je podle vašeho popisu a uvede vás jako zdroj.

Připravuje data AI agent? Dejte mu odkaz na návod pro AI agenty. Obsahuje postup krok za krokem, šablony kódu a kritéria hotové práce. Celá dokumentace je strojově čitelná: llms.txt, MCP server, validátor.

Tři způsoby připojení

Způsob Kdy Co potřebujete
Statické soubory do zhruba 2 000 objektů, data se mění občas manifest.json + data.geojson na libovolném webu (i GitHub Pages)
Vlastní endpoint velké nebo živé sady HTTP GET endpoint, který filtruje podle výřezu mapy (bbox)
Existující WMS / dlaždice máte mapový server jen manifest se zdrojem typu raster

1. Manifest

Jeden JSON, který popisuje vás a vaše datové sady. Povinné je jen minimum: protocol, provider.id, provider.name a u každé sady id, title, source a presentation. Vše ostatní je volitelné, ale pomáhá lidem i AI asistentovi portálu data najít a pochopit (description, keywords, useCases, fields).

Nejmenší rozumný manifest (statické soubory, relativní URL se počítá od adresy manifestu):

{
  "protocol": "0.1",
  "provider": { "id": "obec-priklad", "name": "Obec Příklad", "homepage": "https://www.obec-priklad.cz/" },
  "license": { "name": "CC BY 4.0", "attribution": "© Obec Příklad" },
  "datasets": [
    {
      "id": "lavicky",
      "title": "Lavičky v obci",
      "description": "Veřejné lavičky udržované obcí.",
      "category": "spolecnost",
      "keywords": ["lavička", "posezení", "odpočinek", "park"],
      "useCases": ["turistika"],
      "source": { "type": "geojson", "url": "lavicky.geojson", "mode": "full" },
      "presentation": { "type": "circle", "color": "#0d9488" },
      "fields": [{ "key": "umisteni", "label": "Umístění", "primary": true }]
    }
  ]
}

Úplný příklad se všemi možnostmi (filtry, barvy podle hodnot, seskupování, kartogram, WMS): manifest-kompletni.json.

2. Data

Odpovědí je GeoJSON FeatureCollection se souřadnicemi ve WGS84 v pořadí [lon, lat]. Člen dm je volitelný: nadpis a odkaz u objektu, celkový počet objektů, platnost odpovědi.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1842,
      "geometry": { "type": "Point", "coordinates": [16.6081, 49.1951] },
      "properties": { "druh": "papír", "vyvoz": "2026-10-01" },
      "dm": { "title": "Kontejner Náměstí Svobody", "url": "https://www.mesto-priklad.cz/odpady/1842" }
    }
  ],
  "dm": { "total": 1, "ttl": 3600 }
}

Jak se portál ptá

Režim full – celá sada jedním dotazem. Režim bbox – portál pošle výřez mapy zarovnaný na dlaždice a úroveň přiblížení, plus filtry nastavené uživatelem:

GET https://data.mesto-priklad.cz/datovamapa/kontejnery?bbox=16.523438,49.152970,16.699219,49.267805&zoom=11&limit=5000&lang=cs&protocol=0.1&druh=papír,plast
Accept: application/geo+json, application/json
User-Agent: DatovaMapa/0.1 (+https://datovamapa.cz/dokumentace/pro-poskytovatele)

Vraťte nejvýš limit objektů (max. 5 000). U velkých sad nastavte coverage.minZoom, nebo při malém přiblížení vracejte agregovaná data.

3. Vizualizace

presentation.type Geometrie Typické použití
circle body místa, barva podle kategorie, velikost podle hodnoty, seskupování
heatmap body hustota výskytu, volitelně vážená hodnotou
line linie trasy, sítě, toky
fill plochy území, kartogram podle hodnoty
raster dlaždice hotové mapové vrstvy (WMS, XYZ); legendu uveďte v legend
auto cokoli výchozí vykreslení

Barvy jsou vždy v hex zápisu. Barva může záviset na vlastnosti objektu – podle kategorie (categorical), plynule (interpolate) nebo po intervalech (step). Podrobnosti v protokolu. Další typy budeme přidávat; typ, který portál nezná, vykreslí jako auto.

Data, jejichž hodnota se mění v čase (počet obyvatel, ceny, měření), mají ve standardu vlastní zobrazení: u každého objektu pošlete řadu hodnot v dm.chart a portál ji ukáže jako graf v detailu. Když jde hlavně o to, zda hodnota roste, nebo klesá, nastavte color: { "type": "trend" } – portál z grafu sám obarví objekty zeleně, šedě a červeně a doplní legendu. Podrobnosti v protokolu.

4. Ověření

Než manifest pošlete, nechte ho zkontrolovat validátorem. Vrací chyby i doporučení se stabilními kódy a radami, jak je opravit:

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

Druhý příkaz udělá živý test: stáhne manifest a na každou sadu pošle stejný dotaz, jaký by poslal portál.

5. Registrace

Až validátor hlásí "valid": true, zaregistrujte URL manifestu na datovamapa.cz/registrace, přes API nebo MCP nástroj registrovat_poskytovatele:

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

Portál manifest znovu zkontroluje živým testem. Pak platí:

  • Data jsou hned dostupná, ale neschválená. Každá sada má svou stránku /mapa/{provider}/{dataset}. Před zobrazením dat se tam ukáže varování, že data nahrála třetí strana a provozovatel je zatím nezkontroloval. Data se načtou až po potvrzení uživatelem. Stránka je mimo vyhledávače. Přehled je na neschválených datech.
  • Po schválení provozovatelem se data objeví v katalogu, ve vyhledávání a na stránkách za obce.
  • Schválení platí pro konkrétní obsah manifestu. Když manifest změníte, data se do nového schválení zobrazují zase jen s varováním. Data samotná (GeoJSON) můžete měnit průběžně.
  • provider.id je první registrací obsazené. Neměňte ho, ani URL manifestu.

Registrací potvrzujete, že data smíte zveřejnit pod uvedenou licencí a že neobsahují osobní údaje. Provozovatel může registraci kdykoli zamítnout; data pak z portálu zmizí.

Cache a podmínky

  • Odpovědi držíme v cache po dobu cache.ttl (výchozí 5 minut), aby se váš server nezatěžoval opakovanými dotazy. Při výpadku můžeme krátce zobrazit poslední známá data s upozorněním.
  • V zájmu rychlosti, úspory vašich zdrojů, udržitelnosti, propojování souvislostí mezi zdroji a práce s velkými daty si data můžeme ukládat i do vlastní datové vrstvy. Pokud to nechcete, nastavte u sady cache.store: false.
  • Vždy vás uvádíme jako zdroj podle údajů v licenci manifestu.
  • Na data se ptáme jen u registrovaných poskytovatelů, s časovým limitem 10 s a limitem velikosti odpovědi 15 MB.
  • Nezveřejňujte osobní údaje. Za obsah dat odpovídá poskytovatel.

Odkazy