# Pripojte svoje dáta do DátovejMapy {#pripojte-sva-data-do-datovemapy}

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](https://datovamapa.sk/dokumentacia/pre-ai-agentov.md). Obsahuje postup krok za krokom, šablóny kódu a kritériá hotovej práce. Celá dokumentácia je strojovo čitateľná: [llms.txt](https://datovamapa.sk/llms.txt), [MCP server](https://datovamapa.sk/dokumentacia/api.md#mcp-server), [validátor](https://datovamapa.sk/dokumentacia/api.md#validator).

## Tri spôsoby pripojenia {#tri-zpusoby-pripojeni}

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

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

## 2. Dáta {#2-data}

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.

```json data
{
  "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 {#jak-se-portal-pta}

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:

```http
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 {#3-vizualizace}

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

## 4. Overenie {#4-overeni}

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

```bash
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 {#5-registrace}

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

```bash
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í:

- **Dáta sú hneď dostupné, ale neschválené.** Každá sada má svoju stránku `/mapa/{provider}/{dataset}`. Pred zobrazením dát sa tam ukáže varovanie, že dáta nahrala tretia strana a prevádzkovateľ ich zatiaľ nepreveril. Dáta sa načítajú až po potvrdení používateľom. Stránka je mimo vyhľadávačov. Prehľad je na [neschválených dátach](https://datovamapa.sk/neschvalene-data).
- **Po schválení prevádzkovateľom** sa dáta objavia v [katalógu](https://datovamapa.sk/zdroje.md), vo vyhľadávaní a na stránkach za obce.
- **Schválenie platí pre konkrétny obsah manifestu.** Ak manifest zmeníte, dáta sa do nového schválenia zobrazujú opäť len s varovaním. Dáta samotné (GeoJSON) môžete meniť priebežne.
- `provider.id` je prvou registráciou obsadené. Nemeňte ho, ani URL manifestu.

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 {#cache-a-podminky}

- Odpovede držíme v cache po dobu `cache.ttl` (predvolene 5 minút), aby sa váš server nezaťažoval opakovanými dopytmi. Pri výpadku môžeme krátko zobraziť posledné známe dáta s upozornením.
- V záujme rýchlosti, úspory vašich zdrojov, udržateľnosti, prepájania súvislostí medzi zdrojmi a práce s veľkými dátami si dáta môžeme ukladať aj do vlastnej dátovej vrstvy. Ak to nechcete, nastavte pri sade `cache.store: false`.
- Vždy vás uvádzame ako zdroj podľa údajov v licencii manifestu.
- Na dáta sa pýtame len pri registrovaných poskytovateľoch, s časovým limitom 10 s a limitom veľkosti odpovede 15 MB.
- Nezverejňujte osobné údaje. Za obsah dát zodpovedá poskytovateľ.

## Odkazy {#odkazy}

- [Protokol 0.1 – úplná špecifikácia](https://datovamapa.sk/dokumentacia/protokol.md)
- [Návod pre AI agentov](https://datovamapa.sk/dokumentacia/pre-ai-agentov.md)
- [API portálu, validátor a MCP server](https://datovamapa.sk/dokumentacia/api.md)
- [JSON Schema manifestu](https://datovamapa.sk/schema/0.1/manifest.json) · [JSON Schema dát](https://datovamapa.sk/schema/0.1/data.json) · [OpenAPI kontrakt poskytovateľa](https://datovamapa.sk/schema/0.1/provider-openapi.json)
- Referenčná implementácia (vymyslené dáta, v katalógu portálu nie je): [manifest](https://datovamapa.sk/api/sample/manifest), [dáta](https://datovamapa.sk/api/sample/krajska-mesta)