# Podłącz swoje dane do portalu MapaDanych {#pripojte-sva-data-do-datovemapy}

MapaDanych to otwarty portal, który pokazuje dane z wielu źródeł na jednej mapie. Nie musisz zajmować się mapą, stylami ani serwerem map. Wystarczy opublikować **manifest** (opis Twoich danych) i **dane w formacie GeoJSON**. Portal odpytuje dane w chwili, gdy użytkownik je włączy, rysuje je zgodnie z Twoim opisem i wskazuje Cię jako źródło.

> **Dane przygotowuje agent AI?** Daj mu odnośnik do [instrukcji dla agentów AI](https://mapadanych.pl/dokumentacja/dla-agentow-ai.md). Zawiera procedurę krok po kroku, szablony kodu i kryteria ukończenia pracy. Cała dokumentacja jest czytelna maszynowo: [llms.txt](https://mapadanych.pl/llms.txt), [serwer MCP](https://mapadanych.pl/dokumentacja/api.md#mcp-server), [walidator](https://mapadanych.pl/dokumentacja/api.md#validator).

## Trzy sposoby podłączenia {#tri-zpusoby-pripojeni}

| Sposób | Kiedy | Czego potrzebujesz |
|---|---|---|
| **Pliki statyczne** | do około 2 000 obiektów, dane zmieniają się od czasu do czasu | `manifest.json` + `data.geojson` na dowolnej stronie (także GitHub Pages) |
| **Własny endpoint** | duże zbiory lub dane na żywo | endpoint HTTP GET, który filtruje według wycinka mapy (`bbox`) |
| **Istniejące WMS / kafle** | masz serwer map | tylko manifest ze źródłem typu `raster` |

## 1. Manifest {#1-manifest}

Jeden JSON, który opisuje Ciebie i Twoje zbiory danych. Obowiązkowe jest tylko minimum: `protocol`, `provider.id`, `provider.name`, a przy każdym zbiorze `id`, `title`, `source` i `presentation`. Wszystko inne jest opcjonalne, ale pomaga ludziom i asystentowi AI portalu znaleźć i zrozumieć dane (`description`, `keywords`, `useCases`, `fields`).

Najmniejszy sensowny manifest (pliki statyczne, względny URL liczony jest od adresu manifestu):

```json manifest
{
  "protocol": "0.1",
  "provider": { "id": "gmina-przyklad", "name": "Gmina Przykład", "homepage": "https://www.gmina-przyklad.pl/" },
  "license": { "name": "CC BY 4.0", "attribution": "© Gmina Przykład" },
  "datasets": [
    {
      "id": "lavicky",
      "title": "Ławki w gminie",
      "description": "Publiczne ławki utrzymywane przez gminę.",
      "category": "society",
      "keywords": ["ławka", "siedzisko", "odpoczynek", "park"],
      "useCases": ["tourism"],
      "source": { "type": "geojson", "url": "lavicky.geojson", "mode": "full" },
      "presentation": { "type": "circle", "color": "#0d9488" },
      "fields": [{ "key": "umisteni", "label": "Lokalizacja", "primary": true }]
    }
  ]
}
```

Pełny przykład ze wszystkimi możliwościami (filtry, kolory według wartości, grupowanie, kartogram, WMS): [manifest-complete.json](https://mapadanych.pl/przyklady/manifest-complete.json).

## 2. Dane {#2-data}

Odpowiedzią jest GeoJSON `FeatureCollection` ze współrzędnymi w WGS84 w kolejności `[lon, lat]`. Element `dm` jest opcjonalny: nagłówek i odnośnik przy obiekcie, łączna liczba obiektów, ważność odpowiedzi.

```json data
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1842,
      "geometry": { "type": "Point", "coordinates": [19.9449, 50.0647] },
      "properties": { "druh": "papier", "vyvoz": "2026-10-01" },
      "dm": { "title": "Kontener ul. Główna", "url": "https://www.miasto-przyklad.pl/odpady/1842" }
    }
  ],
  "dm": { "total": 1, "ttl": 3600 }
}
```

### Jak portal odpytuje dane {#jak-se-portal-pta}

Tryb `full` – cały zbiór jednym zapytaniem. Tryb `bbox` – portal wysyła wycinek mapy wyrównany do kafli i poziom przybliżenia oraz filtry ustawione przez użytkownika:

```http
GET https://data.miasto-przyklad.pl/datovamapa/kontejnery?bbox=19.863281,50.064192,20.039063,50.176898&zoom=11&limit=5000&lang=pl&protocol=0.1&druh=papier,plast
Accept: application/geo+json, application/json
User-Agent: DatovaMapa/0.1 (+https://mapadanych.pl/dokumentacja/dla-dostawcow)
```

Zwróć najwyżej `limit` obiektów (maks. 5 000). Przy dużych zbiorach ustaw `coverage.minZoom` albo przy małym przybliżeniu zwracaj dane zagregowane.

Dostawca może poza danymi oferować także **szczegóły obiektu** na żądanie (rozkład jazdy, bogatszy opis, wyróżnienie na mapie): pole `detail: { url }` w zbiorze, szablon z symbolem `{id}`. Zob. [protokół](https://datovamapa.cz/dokumentace/protokol.md#detail-objektu).

## 3. Wizualizacja {#3-vizualizace}

| `presentation.type` | Geometria | Typowe zastosowanie |
|---|---|---|
| `circle` | punkty | miejsca, kolor według kategorii, wielkość według wartości, grupowanie |
| `heatmap` | punkty | gęstość występowania, opcjonalnie ważona wartością |
| `line` | linie | trasy, sieci, przepływy |
| `fill` | powierzchnie | obszary, kartogram według wartości |
| `raster` | kafle | gotowe warstwy mapowe (WMS, XYZ); legendę podaj w `legend` |
| `auto` | cokolwiek | domyślne rysowanie |

Kolory są zawsze w zapisie hex. Kolor może zależeć od właściwości obiektu – według kategorii (`categorical`), płynnie (`interpolate`) lub w przedziałach (`step`). Szczegóły w [protokole](https://mapadanych.pl/dokumentacja/protokol.md#presentation). Kolejne typy będziemy dodawać; typ, którego portal nie zna, zostanie narysowany jako `auto`.

Dane, których wartość zmienia się w czasie (liczba ludności, ceny, pomiary), mają w standardzie własne wyświetlanie: przy każdym obiekcie wyślij szereg wartości w `dm.chart`, a portal pokaże go jako wykres w szczegółach. Jeśli chodzi głównie o to, czy wartość rośnie, czy maleje, ustaw `color: { "type": "trend" }` – portal na podstawie wykresu sam pokoloruje obiekty na zielono, szaro i czerwono i uzupełni legendę. Szczegóły w [protokole](https://mapadanych.pl/dokumentacja/protokol.md#vyvoj-v-case-a-trend).

## 4. Weryfikacja {#4-overeni}

Zanim wyślesz manifest, sprawdź go walidatorem. Zwraca błędy i zalecenia ze stabilnymi kodami oraz wskazówkami, jak je naprawić:

```bash
curl -X POST https://mapadanych.pl/api/validate -H 'Content-Type: application/json' --data @manifest.json
curl 'https://mapadanych.pl/api/validate?manifestUrl=https://data.miasto-przyklad.pl/datovamapa/manifest.json'
```

Drugie polecenie wykonuje test na żywo: pobiera manifest i do każdego zbioru wysyła takie samo zapytanie, jakie wysłałby portal.

## 5. Rejestracja {#5-registrace}

Gdy walidator zgłasza `"valid": true`, zarejestruj URL manifestu na [mapadanych.pl/rejestracja](https://mapadanych.pl/rejestracja), przez API lub narzędziem MCP `register_provider`:

```bash
curl -X POST https://mapadanych.pl/api/registration -H 'Content-Type: application/json' --data '{"manifestUrl": "https://data.miasto-przyklad.pl/datovamapa/manifest.json"}'
```

Portal ponownie sprawdzi manifest testem na żywo. Następnie:

- **Dane są od razu dostępne, ale niezatwierdzone.** Każdy zbiór ma swoją stronę `/mapa/{provider}/{dataset}`. Przed wyświetleniem danych pojawia się tam ostrzeżenie, że dane wgrała strona trzecia i operator ich jeszcze nie sprawdził. Dane ładują się dopiero po potwierdzeniu przez użytkownika. Strona nie jest indeksowana przez wyszukiwarki. Przegląd znajduje się na stronie [niezatwierdzonych danych](https://mapadanych.pl/niezatwierdzone-dane).
- **Po zatwierdzeniu przez operatora** dane pojawią się w [katalogu](https://mapadanych.pl/zrodla.md), w wyszukiwaniu i na stronach gmin.
- **Zatwierdzenie dotyczy konkretnej treści manifestu.** Jeśli zmienisz manifest, dane do ponownego zatwierdzenia znów wyświetlają się tylko z ostrzeżeniem. Same dane (GeoJSON) możesz zmieniać na bieżąco.
- `provider.id` zostaje zajęte przy pierwszej rejestracji. Nie zmieniaj go ani URL manifestu.

Rejestrując się, potwierdzasz, że możesz opublikować dane na podanej licencji i że nie zawierają one danych osobowych. Operator może w każdej chwili odrzucić rejestrację; dane znikną wtedy z portalu.

## Cache i warunki {#cache-a-podminky}

- Odpowiedzi trzymamy w cache przez czas `cache.ttl` (domyślnie 5 minut), aby Twój serwer nie był obciążany powtarzanymi zapytaniami. W razie awarii możemy przez krótki czas wyświetlać ostatnie znane dane z ostrzeżeniem.
- Dane na żywo (`live.interval`): otwarta mapa sama odświeża zbiór w podanym interwale. Ustaw interwał co najmniej na `cache.ttl`, inaczej mapa pyta częściej, niż zmieniają się dane; równoległe zapytania o te same dane portal łączy w jedno zapytanie do Twojego serwera.
- W interesie szybkości, oszczędzania Twoich zasobów, trwałości, łączenia kontekstów między źródłami i pracy z dużymi danymi możemy także zapisywać dane we własnej warstwie danych. Jeśli tego nie chcesz, ustaw dla zbioru `cache.store: false`.
- Zawsze wskazujemy Cię jako źródło zgodnie z informacjami w licencji manifestu.
- Dane odpytujemy tylko u zarejestrowanych dostawców, z limitem czasu 10 s i limitem rozmiaru odpowiedzi 15 MB.
- Nie publikuj danych osobowych. Za treść danych odpowiada dostawca.

## Odnośniki {#odkazy}

- [Protokół 0.1 – pełna specyfikacja](https://mapadanych.pl/dokumentacja/protokol.md)
- [Instrukcja dla agentów AI](https://mapadanych.pl/dokumentacja/dla-agentow-ai.md)
- [API portalu, walidator i serwer MCP](https://mapadanych.pl/dokumentacja/api.md)
- [JSON Schema manifestu](https://mapadanych.pl/schema/0.1/manifest.json) · [JSON Schema danych](https://mapadanych.pl/schema/0.1/data.json) · [Kontrakt OpenAPI dostawcy](https://mapadanych.pl/schema/0.1/provider-openapi.json)
- Implementacja referencyjna (zmyślone dane, nie ma jej w katalogu portalu): [manifest](https://mapadanych.pl/api/sample/manifest), [dane](https://mapadanych.pl/api/sample/krajska-mesta)