# 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](https://datovamapa.cz/dokumentace/pro-ai-agenty.md). Obsahuje postup krok za krokem, šablony kódu a kritéria hotové práce. Celá dokumentace je strojově čitelná: [llms.txt](https://datovamapa.cz/llms.txt), [MCP server](https://datovamapa.cz/dokumentace/api.md#mcp-server), [validátor](https://datovamapa.cz/dokumentace/api.md#validator).

## 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):

```json manifest
{
  "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](https://datovamapa.cz/priklady/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.

```json data
{
  "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:

```http
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](https://datovamapa.cz/dokumentace/protokol.md#presentation). 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](https://datovamapa.cz/dokumentace/protokol.md#vyvoj-v-case-a-trend).

## 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:

```bash
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](https://datovamapa.cz/registrace), přes API nebo MCP nástroj `registrovat_poskytovatele`:

```bash
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](https://datovamapa.cz/neschvalena-data).
- **Po schválení provozovatelem** se data objeví v [katalogu](https://datovamapa.cz/zdroje.md), 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

- [Protokol 0.1 – úplná specifikace](https://datovamapa.cz/dokumentace/protokol.md)
- [Návod pro AI agenty](https://datovamapa.cz/dokumentace/pro-ai-agenty.md)
- [API portálu, validátor a MCP server](https://datovamapa.cz/dokumentace/api.md)
- [JSON Schema manifestu](https://datovamapa.cz/schema/0.1/manifest.json) · [JSON Schema dat](https://datovamapa.cz/schema/0.1/data.json) · [OpenAPI kontrakt poskytovatele](https://datovamapa.cz/schema/0.1/poskytovatel-openapi.json)
- Referenční implementace (smyšlená data, v katalogu portálu není): [manifest](https://datovamapa.cz/api/ukazka/manifest), [data](https://datovamapa.cz/api/ukazka/krajska-mesta)