# MapaDanych

> Otwarty interfejs do wizualizacji danych na mapie. Każdy, kto ma dane z lokalizacją, publikuje manifest i dane GeoJSON zgodnie z protokołem 0.1; portal MapaDanych je wczytuje, weryfikuje, zapisuje w cache i wyświetla na mapie razem z danymi z innych źródeł, z podaniem źródła.

Portal prowadzi vrealmatic.com (https://vrealmatic.com/web).

Agenci, którzy odpowiadają na pytania o miejsce („czy adres leży na terenie zalewowym?”, „jakie jest powietrze w Krakowie?”), korzystają z serwera MCP https://mapadanych.pl/mcp (narzędzia `find_place`, `nearby`, `summary`, `catalog`) albo z API HTTP: `GET https://mapadanych.pl/api/places?query=…`, `GET https://mapadanych.pl/api/nearby?point=lon,lat&datasets=…`, `GET https://mapadanych.pl/api/summary/{provider}/{dataset}?municipality=…`. Instrukcja: https://mapadanych.pl/dokumentacja/asystenci-ai.md

Dane u dostawców zwykle przygotowują agenci AI. Sposób postępowania opisuje instrukcja dla agentów AI; gotową pracę sprawdza walidator (`POST https://mapadanych.pl/api/validate`, test na żywo `GET https://mapadanych.pl/api/validate?manifestUrl=…`). To samo oferuje serwer MCP https://mapadanych.pl/mcp (Streamable HTTP, bez uwierzytelniania). Dokumentacja jest po polsku; każda strona ma wersję markdown z rozszerzeniem `.md`.

## Dokumentacja

- [Instrukcja dla agentów AI](https://mapadanych.pl/dokumentacja/dla-agentow-ai.md): Postępowanie krok po kroku, zasady, szablony kodu i kryteria ukończonej pracy dla agenta, który przygotowuje dane dostawcy.
- [Dane dla asystentów AI](https://mapadanych.pl/dokumentacja/asystenci-ai.md): Jak podłączyć portal MapaDanych do asystenta AI (MCP, HTTP API) i pytać o miejsca i dane.
- [Dla dostawców danych](https://mapadanych.pl/dokumentacja/dla-dostawcow.md): Jak podłączyć dane: pliki statyczne, własny endpoint lub WMS; manifest, dane, wizualizacje, weryfikacja, warunki.
- [Protokol 0.1](https://mapadanych.pl/dokumentacja/protokol.md): Normatywna specyfikacja manifestu, zapytania o dane, odpowiedzi i cache.
- [API portalu i serwer MCP](https://mapadanych.pl/dokumentacja/api.md): Katalog, dane, walidator, narzędzia MCP, linki do mapy i kody wyników walidacji.
- [O projekcie](https://mapadanych.pl/dokumentacja/o-projekcie.md): Wizja portalu MapaDanych, zasady i plan rozwoju.

## Schematy i kontrakty

- [JSON Schema manifestu](https://mapadanych.pl/schema/0.1/manifest.json): co dostawca publikuje o sobie i swoich zbiorach danych
- [JSON Schema danych](https://mapadanych.pl/schema/0.1/data.json): odpowiedź GeoJSON endpointu danych
- [OpenAPI dostawcy](https://mapadanych.pl/schema/0.1/provider-openapi.json): kontrakt endpointów, które implementuje dostawca (można z niego wygenerować serwer)
- [OpenAPI portalu](https://mapadanych.pl/openapi.json): katalog, dane, miejsce i okolica, podsumowania, walidator

## Przykłady

- [manifest-minimal.json](https://mapadanych.pl/przyklady/manifest-minimal.json): Najmniejszy sensowny manifest: statyczny plik GeoJSON, tryb full.
- [manifest-complete.json](https://mapadanych.pl/przyklady/manifest-complete.json): Manifest ze wszystkimi głównymi możliwościami: bbox, filtry, kolory według wartości, grupowanie, kartogram, WMS.
- [data-points.json](https://mapadanych.pl/przyklady/data-points.json): Odpowiedź z punktami wraz z rozszerzeniem dm.
- [detail-jizda.json](https://mapadanych.pl/przyklady/detail-jizda.json): Szczegóły obiektu na żądanie: przejazd pociągu z osią czasu przystanków i trasą do wyróżnienia na mapie.
- [data-doprava.json](https://mapadanych.pl/przyklady/data-doprava.json): Odpowiedź zbioru z profilem transit_vehicles: pojazdy transportu publicznego z dm.transit.
- [data-polygons.json](https://mapadanych.pl/przyklady/data-polygons.json): Odpowiedź z obszarem (polygon) i wartością liczbową do kartogramu.
- [Przykładowy dostawca](https://mapadanych.pl/api/sample/manifest): referencyjna implementacja protokołu przez HTTP (dane fikcyjne, nie ma go w katalogu)

## Dane w portalu

- [Katalog w markdownie](https://mapadanych.pl/zrodla.md): 43 zbiorów od 18 dostawców, z właściwościami i parametrami
- [Katalog w JSON](https://mapadanych.pl/api/catalog)

## Optional

- [Cała dokumentacja w jednym pliku](https://mapadanych.pl/llms-full.txt)

---

<!-- https://mapadanych.pl/dokumentacja/dla-agentow-ai.md -->

# Instrukcja dla agentów AI: podłączenie danych do portalu MapaDanych {#navod-pro-ai-agenty-pripojeni-dat-do-datovemapy}

Ten dokument jest przeznaczony dla agentów AI, którzy przygotowują dane dla portalu MapaDanych. Dostawcą może być każdy, kto ma dane z lokalizacją. Opisuje cel, procedurę, zasady i kryteria ukończenia pracy. Człowiek, który kieruje agentem, znajdzie przystępniejszą wersję w [przewodniku dla dostawców](https://mapadanych.pl/dokumentacja/dla-dostawcow.md).

## Cel {#cil}

Opublikować przez HTTPS:

1. **manifest** – JSON zgodny ze [schematem manifestu](https://mapadanych.pl/schema/0.1/manifest.json),
2. dla każdego zbioru danych **źródło danych** – plik GeoJSON lub endpoint zgodny ze [schematem danych](https://mapadanych.pl/schema/0.1/data.json) i [kontraktem OpenAPI dostawcy](https://mapadanych.pl/schema/0.1/provider-openapi.json), ewentualnie istniejące kafle rastrowe / WMS,

tak, aby [walidator](https://mapadanych.pl/dokumentacja/api.md#validator) zwrócił `"valid": true` i jak najmniej ostrzeżeń.

## Co przeczytać {#co-si-nacist}

| Źródło | Dlaczego |
|---|---|
| [llms.txt](https://mapadanych.pl/llms.txt) | spis całej dokumentacji |
| [Protokół 0.1](https://mapadanych.pl/dokumentacja/protokol.md) | specyfikacja normatywna – w razie wątpliwości obowiązuje ona |
| [JSON Schema manifestu](https://mapadanych.pl/schema/0.1/manifest.json), [danych](https://mapadanych.pl/schema/0.1/data.json) | dokładne typy, limity i opisy pól |
| [OpenAPI dostawcy](https://mapadanych.pl/schema/0.1/provider-openapi.json) | kontrakt endpointu, można z niego wygenerować serwer |
| [manifest-complete.json](https://mapadanych.pl/przyklady/manifest-complete.json), [manifest-minimal.json](https://mapadanych.pl/przyklady/manifest-minimal.json) | poprawne wzory |
| [data-points.json](https://mapadanych.pl/przyklady/data-points.json), [data-polygons.json](https://mapadanych.pl/przyklady/data-polygons.json) | poprawne wzory odpowiedzi |
| [Katalog](https://mapadanych.pl/zrodla.md) | co już jest w portalu – nie twórz duplikatów, inspiruj się słowami kluczowymi |

Jeśli potrafisz korzystać z MCP, połącz się z serwerem `https://mapadanych.pl/mcp` (Streamable HTTP, bez uwierzytelniania). Narzędzia `documentation`, `schema`, `example`, `validate_manifest`, `validate_data` i `catalog` obejmują wszystko, co jest w tej instrukcji. Zob. [serwer MCP](https://mapadanych.pl/dokumentacja/api.md#mcp-server).

## Procedura {#postup}

### 1. Inwentaryzacja danych {#1-inventura-dat}

Ustal, jakie dane przestrzenne ma dostawca: bazy danych (PostGIS, MS SQL), pliki GIS (SHP, GPKG, KML, CSV ze współrzędnymi), istniejące API, usługi WMS/WMTS. Dla każdego źródła ustal:

- typ geometrii (punkty / linie / powierzchnie),
- układ współrzędnych (w Polsce często **PUWG 1992, EPSG:2180** – trzeba przeliczyć),
- liczbę obiektów i jak często się zmieniają,
- licencję i kto może ją zatwierdzić,
- czy zawiera **dane osobowe** (imiona i nazwiska, numery PESEL, adresy osób fizycznych, numery rejestracyjne pojazdów…).

### 2. Projekt zbiorów danych {#2-navrh-datovych-sad}

- Jeden zbiór = jeden rodzaj obiektów z jednym sposobem wyświetlania. Kontenery i mapę hałasu umieść w dwóch zbiorach.
- `id` zbioru i dostawcy: małe litery bez znaków diakrytycznych, cyfry, łączniki (`kontenery-na-odpady`). Po publikacji go nie zmieniaj – jest częścią odnośników.
- Wybór źródła:

| Sytuacja | `source` |
|---|---|
| do ~2 000 obiektów, zmieniają się najwyżej raz dziennie | plik statyczny, `"type": "geojson", "mode": "full"` |
| więcej obiektów lub dane na żywo | endpoint, `"mode": "bbox"`, ustaw `coverage.bbox`, a przy dużych zbiorach `coverage.minZoom` |
| istnieją już kafle WMS / XYZ | `"type": "raster"` z szablonem `{bbox-epsg-3857}` lub `{z}/{x}/{y}`; uzupełnij `presentation.legend` (kolory i etykiety z legendy usługi, np. ArcGIS `…/MapServer/legend?f=json` lub WMS `GetLegendGraphic`) |

### 3. Konwersja danych {#3-prevod-dat}

- Współrzędne **WGS84 (EPSG:4326), kolejność `[lon, lat]`**. Dla Polski to mniej więcej `[19, 52]`, a nie `[52, 19]`.
- Zaokrąglij do 6 miejsc po przecinku (≈ 10 cm), reszta tylko powiększa odpowiedź.
- Wielokąty muszą mieć zamknięte pierścienie (pierwszy punkt = ostatni).
- Każdy obiekt powinien mieć stabilne `id`.
- Właściwości (`properties`) jako proste wartości – ciągi znaków, liczby, wartości logiczne, daty w ISO 8601. Żadnego HTML.
- Liczby jako liczby (`1100`), nie ciągi znaków (`"1100 l"`); jednostkę umieść w `fields[].unit`.

Konwersja pliku GIS do GeoJSON:

```bash
ogr2ogr -f GeoJSON -t_srs EPSG:4326 -lco RFC7946=YES -lco COORDINATE_PRECISION=6 lavicky.geojson vstup.shp
```

Przeliczenie współrzędnych w Pythonie:

```python
from pyproj import Transformer

to_wgs84 = Transformer.from_crs("EPSG:2180", "EPSG:4326", always_xy=True)
lon, lat = to_wgs84.transform(x_puwg, y_puwg)  # always_xy=True zwraca [lon, lat]
```

### 4. Manifest {#4-manifest}

Wypełnij nie tylko pola obowiązkowe, ale też te, od których zależy, czy ktoś dane znajdzie:

- `description` – 1–2 zdania: co zawierają dane, skąd pochodzą, jak są aktualne.
- `keywords` – 5–15 słów i synonimów po polsku, łącznie z formami potocznymi (`śmietnik` obok `kontener`).
- `useCases` – w czym dane pomagają: `construction`, `housing`, `land-purchase`, `agriculture`, `investment`, `transport`, `tourism`, `business`, `public-administration`. Według nich asystent portalu dobiera dane do polecenia typu „chcę budować w gminie X”.
- `category` – jedna z: `territory`, `nature`, `water`, `risks`, `energy`, `transport`, `society`, `economy`, `infrastructure`.
- `fields` – każda właściwość, którą ma widzieć użytkownik: `label`, `type`, `unit`. Jedną oznacz jako `primary` (nagłówek w szczegółach).
- `license` – nazwa i tekst atrybucji. **Nie wymyślaj licencji**; jeśli jej nie znasz, zapytaj człowieka.
- `temporal.updated`, `temporal.frequency` – aktualność danych.
- `temporal.param` – dla danych w czasie (wypadki, pomiary, zdarzenia): klucz parametru typu `range` z latami (`min`/`max` = pierwszy i ostatni rok), którym użytkownik wybiera okres. Odpowiedź powinna wtedy zawierać `dm.timeline` z liczbami według lat (przy wartościach w czasie, takich jak liczba ludności, zamiast tego zbiorczy `dm.chart`), zob. [filtr czasowy](https://mapadanych.pl/dokumentacja/protokol.md#casovy-filtr).
- `live` – tylko dla danych zmieniających się w minutach (pozycje pojazdów, dostępność rowerów): `{ "interval": 60 }` w sekundach, 10 do 3600. Otwarta mapa sama wtedy odświeża zbiór. Ustaw co najmniej `cache.ttl`, inaczej walidator zgłosi `live_interval_below_ttl`.
- **Zmiany w czasie** – sprawdź, czy obiekty mają wartość za wiele okresów (stany według lat, pomiary, ceny). Jeśli tak, wysyłaj ją zawsze przy każdym obiekcie w `dm.chart`; jeśli sensem zbioru jest zmiana, koloruj według trendu. Zob. [zmiany w czasie i trend](https://mapadanych.pl/dokumentacja/protokol.md#vyvoj-v-case-a-trend).

### 5. Wizualizacja {#5-vizualizace}

| Geometria | Odpowiedni typ | Uwaga |
|---|---|---|
| punkty, dziesiątki do setek | `circle` | kolor według kategorii (`categorical`), etykieta przez `label` |
| punkty, tysiące | `circle` z `cluster` lub `heatmap` | mapa ciepła tylko dla gęstości, nie pokazuje pojedynczych obiektów |
| linie | `line` | szerokość może zależeć od wartości |
| powierzchnie z wartością | `fill` + `interpolate` lub `step` | kartogram; `opacity` 0.4–0.6, aby było widać podkład |
| punkty lub powierzchnie, których wartość zmienia się w czasie | `circle` / `fill` + `color: { "type": "trend" }` | gdy chodzi o zmianę (rośnie / maleje); szereg wartości w `dm.chart` przy każdym obiekcie, trend oblicza portal |
| powierzchnie bez wartości | `fill` z jednym kolorem | |

Zasady: kolory hex; kategorie maks. ~8 kolorów; dla wartości użyj skali stopniowej od jasnej do ciemnej; `field` w prezentacji musi odpowiadać właściwości w danych (i w `fields`, z typem liczbowym przy `interpolate`/`step`). Jeśli wartość obiektu ma historię, wyślij ją w `dm.chart` przy dowolnej prezentacji – także przy kartogramie z wyborem roku (wybrany rok w `highlight`).

### 6. Endpoint (tylko przy `mode: "bbox"` lub danych na żywo) {#6-endpoint-jen-u-mode-bbox-nebo-zivych-dat}

Zaimplementuj `GET` zgodnie z [kontraktem OpenAPI](https://mapadanych.pl/schema/0.1/provider-openapi.json):

- query `bbox=minLon,minLat,maxLon,maxLat` – zwróć obiekty przecinające wycinek,
- `zoom` – liczba całkowita; przy małym przybliżeniu możesz zwracać agregacje,
- `limit` – nie zwracaj więcej obiektów; jeśli je obetniesz, ustaw `dm.truncated: true` i `dm.total`,
- własne parametry z `params` (zakres `od,do`, wiele wartości `a,b,c`),
- `Content-Type: application/geo+json` lub `application/json`, HTTPS, odpowiedź w ciągu 1 s,
- nieznane parametry query ignoruj (`lang`, `protocol`, `cursor` możesz pominąć).

CORS nie jest potrzebny – portal wysyła zapytania z serwera.

Python (FastAPI + PostGIS):

```python
from fastapi import FastAPI

app = FastAPI()

@app.get("/datovamapa/kontejnery")
def kontejnery(bbox: str | None = None, zoom: int | None = None, limit: int = 5000, druh: str | None = None):
    west, south, east, north = map(float, bbox.split(",")) if bbox else (-180, -90, 180, 90)
    druhy = druh.split(",") if druh else None
    rows = db.fetch_all(
        """
        SELECT id, druh, objem, vyvoz::text, ST_AsGeoJSON(geom, 6)::json AS geometry
        FROM kontejnery
        WHERE geom && ST_MakeEnvelope(%s, %s, %s, %s, 4326)
          AND (%s::text[] IS NULL OR druh = ANY(%s))
        LIMIT %s
        """,
        (west, south, east, north, druhy, druhy, limit + 1),
    )
    features = [
        {"type": "Feature", "id": r["id"], "geometry": r["geometry"],
         "properties": {"druh": r["druh"], "objem": r["objem"], "vyvoz": r["vyvoz"]}}
        for r in rows[:limit]
    ]
    return {"type": "FeatureCollection", "features": features, "dm": {"truncated": len(rows) > limit, "ttl": 3600}}
```

TypeScript (Cloudflare Worker / Node, dane w pamięci):

```ts
// KONTEJNERY: tablica GeoJSON Feature z punktami, wczytana przy starcie (z bazy danych lub pliku).
declare const KONTEJNERY: { type: "Feature"; id: number; geometry: { type: "Point"; coordinates: [number, number] }; properties: Record<string, unknown> }[];

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const [west, south, east, north] = (url.searchParams.get("bbox") ?? "-180,-90,180,90").split(",").map(Number);
    const limit = Math.min(Number(url.searchParams.get("limit")) || 5000, 5000);
    const inside = KONTEJNERY.filter(({ geometry: { coordinates: [lon, lat] } }) =>
      lon >= west && lon <= east && lat >= south && lat <= north);
    return Response.json(
      { type: "FeatureCollection", features: inside.slice(0, limit), dm: { total: inside.length, truncated: inside.length > limit } },
      { headers: { "Content-Type": "application/geo+json", "Cache-Control": "public, max-age=300" } },
    );
  },
};
```

### 7. Walidacja {#7-validace}

Powtarzaj, dopóki są błędy, i przejrzyj każde ostrzeżenie (napraw je albo świadomie pozostaw i uzasadnij):

```bash
# manifest (bez publikacji)
curl -sX POST https://mapadanych.pl/api/validate -H 'Content-Type: application/json' --data @manifest.json
# dane względem konkretnego zbioru
curl -sX POST https://mapadanych.pl/api/validate -H 'Content-Type: application/json' \
  --data "{\"data\": $(cat lavicky.geojson), \"dataset\": $(jq '.datasets[0]' manifest.json)}"
# test na żywo opublikowanego manifestu i wszystkich źródeł
curl -s 'https://mapadanych.pl/api/validate?manifestUrl=https://www.gmina-przyklad.pl/datovamapa/manifest.json'
```

Odpowiedź: `{ valid, summary, errors: [{ path, code, message, hint? }], warnings: [...] }`, przy teście na żywo dodatkowo `datasets[]` z zapytaniem, czasem odpowiedzi i liczbą obiektów. Znaczenie kodów jest opisane w [API portalu](https://mapadanych.pl/dokumentacja/api.md#kody-nalezu).

### 8. Przekazanie człowiekowi {#8-predani-cloveku}

Na koniec podsumuj:

- URL manifestu i listę zbiorów (id, nazwa, typ źródła, liczba obiektów),
- wynik testu na żywo (`summary`, pozostałe ostrzeżenia i dlaczego zostały),
- co musi potwierdzić człowiek: **licencję i atrybucję**, że dane nie zawierają danych osobowych, kontakt dla portalu,
- jak aktualizować dane (skrypt, cron, źródło prawdy).

Gdy człowiek potwierdzi licencję i treść, zarejestruj manifest: `POST https://mapadanych.pl/api/registration` z `{ "manifestUrl": "…" }` lub narzędziem MCP `register_provider`. Dane będą dostępne jako niezatwierdzone (z ostrzeżeniem, poza katalogiem), dopóki operator ich nie zatwierdzi. Po każdej zmianie manifestu czekają na ponowne zatwierdzenie. Szczegóły: [rejestracja](https://mapadanych.pl/dokumentacja/dla-dostawcow.md#5-registrace).

## Zasady {#pravidla}

- **Nie publikuj danych osobowych** (RODO). W razie wątpliwości dane zagreguj lub pomiń i zapytaj.
- Nie wymyślaj licencji, źródła ani aktualności danych.
- Nie wstawiaj HTML do `properties` ani `dm`; portal wyświetla wszystko jako tekst.
- Nie umieszczaj tajnych kluczy w URL – manifest jest publiczny.
- Nie zmieniaj `provider.id` ani `dataset.id` po publikacji.
- Nie używaj kluczy `bbox`, `zoom`, `limit`, `cursor`, `lang`, `protocol` dla własnych parametrów.
- Maks. 5 000 obiektów i 15 MB na odpowiedź, odpowiedź w ciągu 10 s (celem jest 1 s).

## Kryteria ukończenia pracy {#kriteria-hotove-prace}

- [ ] Manifest jest dostępny przez HTTPS, a test na żywo walidatora zwraca `"valid": true`.
- [ ] Każdy zbiór ma `description`, `keywords`, `useCases`, `category` i (przy GeoJSON) `fields`.
- [ ] Licencja i atrybucja są potwierdzone przez człowieka.
- [ ] Współrzędne są w WGS84 `[lon, lat]`, brak ostrzeżeń `swapped_coordinates` i `outside_coverage`.
- [ ] Żaden zbiór nie zwraca w teście 0 obiektów (`empty_response`), chyba że jest to zamierzone.
- [ ] Obiekty mające wartość za wiele okresów wysyłają `dm.chart` (brak `missing_trend_chart` i `trend_without_chart`).
- [ ] Czas odpowiedzi endpointów jest poniżej 3 s (`slow_response`).
- [ ] Dane nie zawierają danych osobowych.
- [ ] Opisano, jak dane są aktualizowane.

## Polecenie dla agenta (do skopiowania) {#zadani-pro-agenta-ke-zkopirovani}

Człowiek może dać swojemu agentowi ten tekst:

```text
Przygotuj nasze dane przestrzenne dla portalu MapaDanych (https://mapadanych.pl).
Postępuj zgodnie z instrukcją https://mapadanych.pl/dokumentacja/dla-agentow-ai.md
(spis dokumentacji: https://mapadanych.pl/llms.txt, serwer MCP: https://mapadanych.pl/mcp).
Źródła danych: <opisz bazy danych, pliki, usługi>.
Gdzie opublikować: <strona / serwer / repozytorium>.
Licencja: <np. CC BY 4.0, atrybucja „© Gmina Przykład”> – innej nie wymyślaj.
Gotowe, gdy test na żywo walidatora zwraca valid: true i spełnisz kryteria ukończenia pracy.
Na koniec przekaż mi podsumowanie zgodnie z krokiem 8.
```

---

<!-- https://mapadanych.pl/dokumentacja/asystenci-ai.md -->

# Dane z portalu MapaDanych w Twoim asystencie AI {#data-datovemapy-ve-vasem-ai-asistentovi}

MapaDanych łączy publiczne dane z lokalizacją z dziesiątek źródeł: obszary zagrożenia powodziowego, radon, hałas, obszary chronione, jakość powietrza, zabytki, statystyki gmin, wyniki wyborów i wiele innych. Podłącz portal do swojego asystenta AI i zadawaj pytania zwykłym językiem. Asystent sam pobierze dane, zinterpretuje je i poda źródło.

Jest to bezpłatne, bez rejestracji i bez klucza. Wystarczy asystent obsługujący MCP (Model Context Protocol) albo aplikacja, która wywołuje HTTP API.

## O co możesz zapytać {#na-co-se-muzete-zeptat}

- *„Czy adres Floriańska 1 w Krakowie leży na obszarze zagrożenia powodziowego? I jaki jest tam wskaźnik radonowy?”*
- *„Kupuję działkę w gminie Kobierzyce pod Wrocławiem. Co powinienem wiedzieć – zagrożenia, ochrona przyrody, hałas?”*
- *„Jakie jest teraz powietrze w Gdańsku i gdzie jest najbliższa stacja pomiarowa od Marszałkowskiej 10 w Warszawie?”*
- *„Jaka była frekwencja wyborcza we Wrocławiu i jak wypadły partie?”*
- *„Jakie zabytki są w promieniu 500 m od ulicy Długiej 1 w Gdańsku?”*

Asystent znajdzie miejsce w rejestrze adresów, wybierze odpowiednie zbiory danych i zapyta je o punkt lub okolicę. Odpowie z liczbami, źródłem i odnośnikiem do mapy, na której sprawdzisz wynik.

## Podłączenie {#pripojeni}

Adres serwera MCP: `https://mapadanych.pl/mcp` (Streamable HTTP, bez logowania).

| Asystent | Jak podłączyć |
|---|---|
| Claude (web, desktop) | w ustawieniach konektorów dodaj własny konektor z adresem serwera MCP |
| Claude Code | `claude mcp add --transport http mapadanych https://mapadanych.pl/mcp` |
| ChatGPT | w trybie dewelopera (developer mode) dodaj własny konektor / aplikację z adresem serwera MCP |
| inny klient MCP | konfiguracja poniżej |

```json
{ "mcpServers": { "mapadanych": { "type": "http", "url": "https://mapadanych.pl/mcp" } } }
```

Nazwy pozycji w ustawieniach różnią się między asystentami; szukaj „konektory”, „MCP” lub „własne narzędzia”.

Asystent bez MCP może użyć [HTTP API](https://mapadanych.pl/dokumentacja/api.md#misto-a-okoli) opisanego w [OpenAPI](https://mapadanych.pl/openapi.json), np. jako akcji własnego GPT.

## Narzędzia {#nastroje}

| Narzędzie | Do czego |
|---|---|
| `find_place` | adres, ulica lub gmina → współrzędne |
| `nearby` | co jest w punkcie i okolicy: obiekty według odległości, w zbiorach rastrowych (powodzie, radon, hałas…) wartość bezpośrednio w punkcie |
| `summary` | przegląd zbioru dla dowolnej gminy lub całej Polski: liczby, kategorie, najwyższe i najniższe wartości |
| `catalog` | jakie dane ma portal, z wyszukiwaniem według tekstu i miejsca |
| `fetch_data` | surowe dane GeoJSON wraz z geometriami (do własnej analizy) |

Wejścia i wyjścia szczegółowo: [API portalu i serwer MCP](https://mapadanych.pl/dokumentacja/api.md#mcp-server).

## Dla firm i programistów {#pro-firmy-a-vyvojare}

- HTTP API (`/api/places`, `/api/nearby`, `/api/summary/…`, `/api/data/…`) jest publiczne, bez klucza, z CORS `*` (wyjątkiem są [zbiory tylko do wyświetlania](https://mapadanych.pl/dokumentacja/api#data)). Odpowiedzi są w JSON, a portal trzyma je w cache.
- Własny agent dostaje te same dane co mapa: zbiory GeoJSON portal pobiera przez swoje proxy z cache, zbiory rastrowe odpytuje o punkt bezpośrednio u źródła (WMS GetFeatureInfo, ArcGIS identify).
- Każdy zbiór ma własną licencję i atrybucję (`attribution`, `license` w wyniku i w [katalogu](https://mapadanych.pl/zrodla.md)). Przestrzegaj ich przy dalszym wykorzystaniu danych.
- Jeśli chcesz dodać do portalu własne dane, zacznij od [instrukcji dla dostawców](https://mapadanych.pl/dokumentacja/dla-dostawcow.md).

## Co warto wiedzieć {#co-je-dobre-vedet}

- **Dane mają charakter informacyjny.** Portal przejmuje dane od dostawców i nie odpowiada za ich poprawność. Informacje prawnie wiążące (obszary zagrożenia powodziowego, plan miejscowy, ewidencja gruntów i budynków) sprawdź w urzędzie lub u dostawcy. Asystent powinien w odpowiedzi podać źródło i datę danych.
- **Pusty wynik nie zawsze oznacza „nic tu nie ma”.** W zbiorach rastrowych stan `ok` bez wyników oznacza, że w punkcie nic nie ma (np. poza obszarem zagrożenia powodziowego). Stan `unavailable` oznacza, że źródło jest tylko obrazem i nie podaje wartości w punkcie. Wtedy pomoże odnośnik do mapy.
- **Podsumowanie dla gminy** działa dla każdej gminy w Polsce. Przy gminach o tej samej nazwie (Dąbrowa) asystent zapyta o powiat. Konkretne adresy obsłuży `nearby`.
- **Zakres zapytania:** okolica najwyżej 20 km, najwyżej 12 zbiorów w jednym zapytaniu. Zbiory ładowane tylko przy dużym przybliżeniu (drzewa, kontenery) zmniejszą okolicę i poinformują o tym.
- **Prywatność:** portal nie potrzebuje konta ani żadnych informacji o Tobie. Adres, o który pyta asystent, wysyła tylko do wyszukiwarki w rejestrze adresów, a współrzędne do źródeł danych.

---

<!-- https://mapadanych.pl/dokumentacja/dla-dostawcow.md -->

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

---

<!-- https://mapadanych.pl/dokumentacja/protokol.md -->

# Protokół MapaDanych 0.1 {#protokol-datovamapa-0-1}

Normatywny opis interfejsu między dostawcą danych a portalem. W razie sprzeczności z inną dokumentacją obowiązuje ten dokument oraz schematy maszynowe:

- [JSON Schema manifestu](https://mapadanych.pl/schema/0.1/manifest.json) i [JSON Schema danych](https://mapadanych.pl/schema/0.1/data.json) – generowane ze schematów zod w `src/lib/protocol/`,
- [kontrakt OpenAPI dostawcy](https://mapadanych.pl/schema/0.1/provider-openapi.json).

Przygotowanie danych krok po kroku (zwłaszcza dla agentów AI) opisuje [poradnik dla agentów AI](https://mapadanych.pl/dokumentacja/dla-agentow-ai.md), przystępne wprowadzenie znajdziesz w [przewodniku dla dostawców](https://mapadanych.pl/dokumentacja/dla-dostawcow.md). Poprawne wzorce: [manifest-complete.json](https://mapadanych.pl/przyklady/manifest-complete.json), [data-points.json](https://mapadanych.pl/przyklady/data-points.json).

## Przegląd {#prehled}

```
Dostawca                             Portal MapaDanych                 Przeglądarka
────────                             ─────────────────                 ────────────
manifest.json  ◄── GET (cache 10 min) ── rejestr → katalog ──────────► /api/catalog
endpoint danych ◄── GET ?bbox&zoom&… ─── proxy + walidacja + cache ───► /api/data/{provider}/{dataset}
kafelki rastrowe ◄────────────────────────────────────────────────────── bezpośrednio z przeglądarki
```

## Zasady ogólne {#obecna-pravidla}

- Format JSON, kodowanie UTF-8, współrzędne WGS84 (EPSG:4326) w kolejności `[lon, lat]`.
- Komunikacja przez HTTPS (http tylko dla `localhost` podczas programowania).
- **Nieznane pola są ignorowane.** Nieznany typ `presentation` jest renderowany jako `auto`.
- Wersja `protocol` w postaci `major.minor`. Portal przyjmie manifest o tej samej wersji głównej.
- Identyfikatory (`provider.id`, `dataset.id`): małe litery bez znaków diakrytycznych, cyfry, łączniki, maks. 64 znaki. Globalny klucz zbioru to `provider/dataset`.
- Kolory tylko w zapisie szesnastkowym (`#rgb`, `#rrggbb`, `#rrggbbaa`).

## Manifest {#manifest}

| Pole | Wymagane | Opis |
|---|---|---|
| `protocol` | tak | Wersja protokołu, np. `"0.1"` |
| `provider.id` | tak | Identyfikator; musi odpowiadać id w rejestrze portalu |
| `provider.name` | tak | Nazwa wyświetlana jako źródło |
| `provider.description`, `homepage`, `logo`, `contact` | nie | |
| `provider.managedBy` | nie | `provider` (domyślnie) / `portal` – manifest usługi publicznej utrzymuje portal MapaDanych |
| `license` | nie | `{ name, url?, attribution }` – domyślna licencja wszystkich zbiorów |
| `datasets[]` | tak | 1–200 zbiorów danych o unikalnym `id` |

### Zbiór danych {#datova-sada}

| Pole | Wymagane | Opis |
|---|---|---|
| `id`, `title` | tak | |
| `description` | nie | |
| `category` | nie | `territory`, `nature`, `water`, `risks`, `energy`, `transport`, `society`, `economy`, `infrastructure`, `sample`, `other`; inna wartość → Inne |
| `tags`, `keywords` | nie | Do wyszukiwania i dla przyszłego asystenta |
| `useCases` | nie | Cele, do których zbiór się nadaje: `construction`, `housing`, `land-purchase`, `agriculture`, `investment`… |
| `coverage` | nie | `{ bbox?, area?, minZoom?, maxZoom? }` – poniżej `minZoom` portal nie wczytuje danych |
| `temporal` | nie | `{ updated?, frequency?, param? }` – `param` = klucz parametru, którym wybiera się okres (zob. [filtr czasowy](https://mapadanych.pl/dokumentacja/protokol.md#casovy-filtr)) |
| `license` | nie | Nadpisuje licencję dostawcy |
| `source` | tak | Skąd pobierać dane (zob. niżej) |
| `presentation` | tak | Jak dane renderować (zob. niżej) |
| `fields[]` | nie | Opis właściwości obiektów: `key`, `label`, `type`, `unit`, `decimals`, `description`, `primary` |
| `params[]` | nie | Filtry dla użytkownika (zob. niżej) |
| `cache` | nie | `{ ttl?: sekundy, store?: boolean }` |
| `live` | nie | `{ interval: sekundy }` – dane na żywo: otwarta mapa sama odświeża zbiór (10 do 3600 s), zob. [cache](https://datovamapa.cz/dokumentace/protokol.md#cache) |
| `detail` | nie | `{ url }` – szczegóły obiektu na żądanie po kliknięciu (rozkład jazdy, bogatszy opis, wyróżnienie na mapie), zob. [szczegóły obiektu](https://datovamapa.cz/dokumentace/protokol.md#detail-objektu) |
| `profile` | nie | Rodzaj zbioru ze wspólnym zachowaniem w portalu: `transit_vehicles` = bieżące pozycje pojazdów transportu publicznego, zob. [transport](https://datovamapa.cz/dokumentace/protokol.md#doprava) |

### `source` {#source}

**`geojson`** – format natywny.

```json
{ "type": "geojson", "url": "/data/kontenery", "mode": "bbox", "maxFeatures": 5000 }
```

- `url` może być względny wobec URL manifestu. Źródłem może być też **plik statyczny** (`lawki.geojson` obok `manifest.json` na dowolnym hostingu) – w trybie `full` portal nie wymaga żadnych parametrów zapytania, a plik jest poprawnym endpointem.
- `mode: "full"` – cały zbiór jednym zapytaniem (małe zbiory). `mode: "bbox"` – portal pyta o wycinek mapy.
- `maxFeatures` ≤ 5000.

**`raster`** – gotowe kafelki, przeglądarka wczytuje je bezpośrednio ze źródła.

```json
{ "type": "raster", "tiles": ["https://…/{z}/{x}/{y}.png"], "tileSize": 256, "minZoom": 0, "maxZoom": 19 }
```

Szablony obsługują `{z}/{x}/{y}` oraz `{bbox-epsg-3857}` (WMS GetMap). Tylko https.

### `presentation` {#presentation}

| `type` | Geometria | Opcje |
|---|---|---|
| `circle` | punkty | `color`, `radius`, `opacity`, `strokeColor`, `strokeWidth`, `label`, `cluster` |
| `heatmap` | punkty | `weight`, `radius`, `intensity`, `colors[]`, `opacity` |
| `line` | linie | `color`, `width`, `opacity`, `dash[]`, `label` |
| `fill` | powierzchnie | `color`, `opacity`, `outlineColor`, `outlineWidth`, `label` |
| `raster` | kafelki | `opacity` |
| `auto` | cokolwiek | `color` |

Wszystkie typy mają opcjonalną `legend: [{ label, color }]` (maks. 20 pozycji). Portal pokazuje ją w legendzie bezpośrednio na mapie i w wyborze warstw. Dla typów wektorowych potrafi wyprowadzić ją z kolorów, dla `raster` nie – kolory są zapieczone w obrazach kafelków, dlatego legendę rastra podaj ręcznie (np. przejmując ją z legendy usługi WMS / ArcGIS).

**Kolor** (`color`) to albo ciąg szesnastkowy, albo reguła według właściwości obiektu:

```json
{ "field": "druh", "type": "categorical", "values": { "papier": "#2563eb" }, "default": "#64748b" }
{ "field": "hodnota", "type": "interpolate", "stops": [[0, "#f7fcb9"], [100, "#004529"]] }
{ "field": "hodnota", "type": "step", "default": "#eee", "stops": [[10, "#fc8"], [50, "#e34"]] }
{ "type": "trend" }
```

`trend` koloruje obiekty według tego, czy ich wartość w czasie rośnie, stoi w miejscu, czy maleje. Oblicza go portal z wykresu zmian `dm.chart` – zob. [zmiany w czasie i trend](https://mapadanych.pl/dokumentacja/protokol.md#vyvoj-v-case-a-trend).

**Liczba** (`radius`, `width`, `weight`) to liczba albo `{ "field", "type": "interpolate", "stops": [[wartość, liczba], …] }`.

**Etykieta** (`label`): `{ field, minZoom?, color?, size? }`.

### `params` {#params}

Filtr, który użytkownik ustawia w portalu; portal przesyła go jako parametr zapytania `key=value`.

| `type` | Wartość w zapytaniu |
|---|---|
| `enum` | `key=a` (z `options`) |
| `multi-enum` | `key=a,b,c` |
| `number` | `key=42` (w zakresie `min`–`max`) |
| `range` | `key=od,do` |
| `boolean` | `key=true` / `false` |
| `date` | `key=2026-10-06` |
| `date-range` | `key=2026-01-01,2026-12-31` |
| `text` | `key=…` (maks. 200 znaków) |

Klucze `bbox`, `zoom`, `limit`, `cursor`, `lang`, `protocol` są zarezerwowane. Portal wysyła tylko zadeklarowane parametry, a ich wartości wcześniej sprawdza; niewypełniony parametr zastępuje wartością `default`.

### Filtr czasowy {#casovy-filtr}

Dane w czasie (wypadki, pomiary, zdarzenia) mają jeden parametr okresu i odwołują się do niego z `temporal.param`. Portal nie pokazuje go wtedy wśród pozostałych filtrów, lecz jako oś czasu w oknie pod legendą: suwak okresu i wykres słupkowy według lat, na którym okres można wybrać kliknięciem lub przeciągnięciem. Wybrany okres widać też przy warstwie w legendzie.

- Typ `range` z latami – `min` i `max` to pierwszy i ostatni rok danych, wartość `od,do` (np. `2019,2023`, jeden rok `2023,2023`). Obiekty za cały okres zwracaj łącznie (zbiorczo), nie z podziałem na poszczególne lata.
- Typ `date-range` – okres z dokładnością do dni, `2026-01-01,2026-06-30`.

```json manifest
{
  "protocol": "0.1",
  "provider": { "id": "miasto-przyklad", "name": "Miasto Przykład" },
  "license": { "name": "CC BY 4.0", "attribution": "© Miasto Przykład" },
  "datasets": [{
    "id": "nehody",
    "title": "Wypadki drogowe",
    "description": "Wypadki zarejestrowane przez policję według skutków.",
    "category": "transport",
    "keywords": ["wypadek", "wypadek drogowy", "bezpieczeństwo", "obrażenia", "skrzyżowanie"],
    "useCases": ["transport", "housing"],
    "coverage": { "bbox": [19.79, 49.97, 20.22, 50.13], "minZoom": 12 },
    "temporal": { "frequency": "co roku", "param": "obdobi" },
    "source": { "type": "geojson", "url": "https://data.miasto-przyklad.pl/mapadanych/wypadki", "mode": "bbox", "maxFeatures": 5000 },
    "presentation": {
      "type": "circle",
      "color": { "field": "nasledky", "type": "categorical", "values": { "obrażenia": "#dc2626", "szkoda materialna": "#facc15" }, "default": "#facc15" }
    },
    "fields": [
      { "key": "nasledky", "label": "Skutki", "type": "string", "primary": true },
      { "key": "datum", "label": "Data", "type": "date" }
    ],
    "params": [{ "key": "obdobi", "label": "Okres", "type": "range", "min": 2015, "max": 2025, "step": 1, "default": "2025,2025" }]
  }]
}
```

Wykres rysuje portal z `dm.timeline` w odpowiedzi (zob. [odpowiedź z danymi](https://mapadanych.pl/dokumentacja/protokol.md#datova-odpoved)). Przy wartościach w czasie, dla których liczba obiektów nie ma sensu (liczba ludności, cena), wyślij zamiast tego zbiorczy przebieg w `dm.chart` – portal pokaże go przy suwaku jako wykres liniowy, zob. [zmiany w czasie i trend](https://mapadanych.pl/dokumentacja/protokol.md#vyvoj-v-case-a-trend). Bez żadnego z nich zostanie tylko suwak okresu.

### Zmiany w czasie i trend {#vyvoj-v-case-a-trend}

Standardowy sposób prezentacji danych, których wartość przy obiekcie zmienia się w czasie – liczba mieszkańców gminy, cena, zmierzone stężenie, frekwencja odwiedzających. Zawsze, gdy dane mają taki szereg, wysyłaj go; portal sam narysuje z niego wykres i może według niego kolorować.

- **Wykres zmian.** Jeśli obiekt ma wartość za kilka okresów, wyślij ją w `feature.dm.chart` (zob. [odpowiedź z danymi](https://mapadanych.pl/dokumentacja/protokol.md#datova-odpoved)). Portal pokaże ją w szczegółach obiektu jako wykres liniowy z wartością za wybrany okres i zmianą względem jego początku. Dotyczy to także kartogramów, w których rok wybiera się parametrem: wyślij szereg za wszystkie lata, a wybrany rok jako `highlight` z jednakowym `from` i `to`. Gdy zbiór koloruje według wartości liczbowej, okres wybiera się parametrem, a wykresu brak, walidator zgłasza to jako `missing_trend_chart`.
- **Wykres zbiorczy przy legendzie.** Przebieg dla całego obszaru zbioru lub dla wycinka (np. liczbę ludności Polski) wyślij w `dm.chart` odpowiedzi – w takiej samej postaci jak wykres obiektu. Portal pokaże go przy filtrze czasowym, dopóki użytkownik nie otworzy żadnego obiektu, a wybrany okres zaznaczy według `highlight`. Jeśli zbiór koloruje według trendu, linia otrzyma kolor trendu całości – widać wtedy, czy zielone punkty nie powielają po prostu ogólnokrajowego przebiegu.
- **Kolor według trendu.** Jeśli sensem zbioru jest zmiana („rośnie czy maleje?”), ustaw `color: { "type": "trend" }`. Portal z wykresu każdego obiektu obliczy średnią zmianę na jeden okres w % wartości początkowej – w wyróżnionym okresie (`highlight`), w przeciwnym razie dla całego szeregu. Od `threshold` (domyślnie 0,5 %) w górę wartość **rośnie** (zielony), od −`threshold` w dół **maleje** (czerwony), pomiędzy nimi **stoi w miejscu** (szary). Kolory można nadpisać przez `colors: { up, flat, down }`, na przykład gdy wzrost jest niepożądany. Legendę portal wyprowadzi sam, a wykres w szczegółach pokoloruje tak samo jak obiekt na mapie. Obiekt bez wykresu pozostanie jasnoszary (`trend_without_chart`).

Trend opiera się na zmianie względnej, dlatego nadaje się dla wielkości dodatnich (liczby, ceny, stężenia). Wartości w okolicy zera, takie jak saldo migracji, koloruj przez `interpolate`, a zmiany pokazuj tylko wykresem.

```json manifest
{
  "protocol": "0.1",
  "provider": { "id": "wojewodztwo-przyklad", "name": "Województwo Przykład" },
  "license": { "name": "CC BY 4.0", "attribution": "© Województwo Przykład" },
  "datasets": [{
    "id": "vyvoj-obyvatel",
    "title": "Zmiany liczby mieszkańców gmin",
    "description": "Gdzie mieszkańców przybywa, a gdzie ubywa. Kolor według trendu w wybranym okresie, w szczegółach gminy wykres według lat.",
    "category": "society",
    "keywords": ["mieszkańcy", "ludność", "trend", "wzrost", "wyludnianie"],
    "useCases": ["housing", "public-administration"],
    "temporal": { "frequency": "co roku", "param": "obdobi" },
    "source": { "type": "geojson", "url": "https://data.wojewodztwo-przyklad.pl/mapadanych/mieszkancy" },
    "presentation": { "type": "circle", "color": { "type": "trend", "threshold": 0.5 }, "radius": 7 },
    "fields": [
      { "key": "nazev", "label": "Gmina", "type": "string", "primary": true },
      { "key": "obyvatel", "label": "Mieszkańcy na koniec okresu", "type": "integer" }
    ],
    "params": [{ "key": "obdobi", "label": "Okres", "type": "range", "min": 2015, "max": 2025, "step": 1, "default": "2015,2025" }]
  }]
}
```

Odpowiedź wysyła wtedy przy każdej gminie szereg za wszystkie lata, a wybrany okres w `highlight`, na przykład `{ "from": "2015", "to": "2025" }`.

## Zapytanie o dane {#datovy-dotaz}

```
GET {source.url}?bbox=minLon,minLat,maxLon,maxLat&zoom=10&limit=5000&lang=pl&protocol=0.1[&cursor=…][&{params}]
Accept: application/geo+json, application/json
User-Agent: DatovaMapa/0.1 (+https://mapadanych.pl/dokumentacja/dla-dostawcow)
```

- `bbox` i `zoom` tylko w trybie `bbox`. Wycinek jest **wyrównany do kafelków** poziomu `zoom` (liczba całkowita), więc zbliżone widoki prowadzą do tego samego zapytania – zarówno dostawca, jak i portal mogą buforować odpowiedzi.
- `limit` = ile obiektów portal przetworzy maksymalnie.
- Limit czasu odpowiedzi 10 s, rozmiar maks. 15 MB.

## Odpowiedź z danymi {#datova-odpoved}

GeoJSON `FeatureCollection` (RFC 7946). Obsługiwane geometrie: `Point`, `MultiPoint`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`. Obiekty z `geometry: null` są pomijane.

Opcjonalne rozszerzenia:

```json
{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature", "id": 1, "geometry": {…}, "properties": {…},
    "dm": { "title": "…", "description": "…", "url": "https://…", "color": "#e11d48", "chart": {…} }
  }],
  "dm": { "generated": "2026-10-06T08:00:00Z", "ttl": 3600, "total": 1, "truncated": false, "next": "…", "notice": "…", "timeline": […] }
}
```

- `feature.dm` – nagłówek i opis w szczegółach, link do szczegółów u źródła, nadpisanie koloru, wykres zmian.
- `feature.dm.transit` – pojazd transportu publicznego w zbiorach z profilem `transit_vehicles`, zob. [transport](https://datovamapa.cz/dokumentace/protokol.md#doprava).
- `feature.dm.chart` – przebieg jednej wartości obiektu w czasie, który portal narysuje w szczegółach obiektu jako wykres liniowy z wartością za ostatni okres (np. liczba mieszkańców gminy według lat) i z którego oblicza kolor według trendu. `label` mówi, co wykres pokazuje, opcjonalne są `unit`, `decimals`, `note` (uwaga pod wykresem, np. o zmianie metodyki) i `highlight: { from, to }` – wyróżniony okres, zwykle wybrany w filtrze czasowym; portal go podświetli, pokaże wartość na jego końcu, a zmianę i trend liczy od jego początku. Jednakowe `from` i `to` oznaczają jeden okres, np. rok wybrany przy kartogramie – wykres zatrzyma się na nim. `points` to pary `{ period, value }` uporządkowane od najstarszego okresu – `period` to rok, miesiąc lub dzień, tak jak w `dm.timeline`. 2–100 punktów. Wysyłaj go zawsze, gdy obiekt ma wartość za kilka okresów (zob. [zmiany w czasie i trend](https://mapadanych.pl/dokumentacja/protokol.md#vyvoj-v-case-a-trend)).
- `dm.ttl` – ważność odpowiedzi (portal użyje mniejszej z wartości `cache.ttl` i `dm.ttl`).
- `dm.total`, `dm.truncated` – ile jest obiektów łącznie / czy odpowiedź jest skrócona.
- `dm.notice` – krótki komunikat dla użytkownika (wyświetla się przy warstwie).
- `dm.next` – kursor do następnej strony (portal na razie go nie wykorzystuje, zarezerwowane).
- `dm.timeline` – liczby obiektów **w wycinku** według okresów za cały czas, który zbiór obejmuje, niezależnie od wybranego okresu i od `limit` (policz je zapytaniem agregującym, nie ze zwróconych obiektów). Portal rysuje z nich wykres przy legendzie. `period` to rok (`2023`), miesiąc (`2023-05`) lub dzień; opcjonalne `values` dzieli liczbę według wartości właściwości z `color.field`, a wykres koloruje je jak legendę. Maks. 400 okresów.
- `dm.chart` – zbiorczy przebieg wartości dla całego obszaru zbioru lub wycinka (np. liczba ludności Polski), w takiej samej postaci jak `feature.dm.chart`. Portal pokaże go przy filtrze czasowym jako wykres liniowy, gdy odpowiedź nie zawiera `dm.timeline`.

```json data
{
  "type": "FeatureCollection",
  "features": [],
  "dm": {
    "timeline": [
      { "period": "2024", "count": 2366, "values": { "obrażenia": 701, "szkoda materialna": 1665 } },
      { "period": "2025", "count": 1894, "values": { "obrażenia": 652, "szkoda materialna": 1242 } }
    ]
  }
}
```

Zbiorczy przebieg dla całego obszaru zamiast liczby obiektów (wybrany okres 2023–2025):

```json data
{
  "type": "FeatureCollection",
  "features": [],
  "dm": {
    "chart": {
      "label": "Liczba ludności Polski na 31 grudnia",
      "highlight": { "from": "2022", "to": "2025" },
      "points": [
        { "period": "2021", "value": 38036118 },
        { "period": "2022", "value": 37766327 },
        { "period": "2023", "value": 37636508 },
        { "period": "2024", "value": 37489087 },
        { "period": "2025", "value": 37350000 }
      ]
    }
  }
}
```

Obiekt z wykresem zmian w szczegółach:

```json data
{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "id": "1261011",
    "geometry": { "type": "Point", "coordinates": [19.9450, 50.0647] },
    "properties": { "nazev": "Kraków", "obyvatel": 806000 },
    "dm": {
      "chart": {
        "label": "Liczba mieszkańców na 31 grudnia",
        "points": [
          { "period": "2023", "value": 803300 },
          { "period": "2024", "value": 804900 },
          { "period": "2025", "value": 806000 }
        ]
      }
    }
  }]
}
```
- Właściwości z przedrostkiem `__dm_` są zarezerwowane dla portalu i zostają usunięte z odpowiedzi.

## Szczegóły obiektu {#detail-objektu}

Zbiór może oferować szczegóły obiektu na żądanie: po kliknięciu obiektu portal pokazuje okno z właściwości, a pod nim uzupełnia szczegóły pobrane osobno. Przydają się przy bogatszej treści, która nie mieści się we właściwościach: rozkład jazdy pociągu, przebieg przejazdu, wyróżnienie trasy na mapie. Pole `detail` w zbiorze zawiera szablon adresu z symbolem `{id}`, za który portal podstawia `id` obiektu z danych (obiekty muszą więc mieć stabilne `id`). Adres jest https albo względny wobec manifestu; walidator zgłasza szablon bez `{id}` (`detail_url_without_id`) i schemat inny niż https (`detail_url_not_https`).

```json
"detail": { "url": "https://data.example.cz/detail?id={id}" }
```

Odpowiedzią jest JSON `FeatureDetail` (`title` i `generated` są obowiązkowe, pozostałe pola opcjonalne):

- `title`, `subtitle`, `badge { text, color, textColor }` – nagłówek, `status { label, tone }` – stan z tonem `ok`, `warning`, `danger` lub `neutral`,
- `fields[] { label, value }`, `tags[]`, `notes[]` – dodatkowe dane, krótkie etykiety i uwagi,
- `journey.calls[]` – kolejne przystanki (najwyżej 300): `name`, `arrival`, `departure` (obowiązujący czas), `scheduledArrival`, `scheduledDeparture` (rozkład), `estimated` (czas jest szacunkiem), `platform`, `state` (`passed`, `current`, `upcoming`); czasy są w ISO 8601 z przesunięciem strefy,
- `highlight` – GeoJSON `FeatureCollection` do wyróżnienia na mapie, do około 200 kB: linie z właściwością `role` `passed` (przebyta część, przyciemniona) lub `upcoming`, punkty z `role` `stop` lub `current` i `name` jako etykietą,
- `color`, `url`, `notice`, `generated`, `ttl` (jak długo szczegóły są ważne, w sekundach).

Dopóki szczegóły są otwarte, mapa odświeża je z interwałem `live.interval` zbioru. Portal buforuje odpowiedzi według `ttl` i sprawdza ich schemat tak samo jak dane. Nieznane `id` dostawca zwraca jako `404`.

```json detail
{
  "title": "RJ 1000",
  "subtitle": "→ Praha-Zahradní Město · RegioJet a.s.",
  "badge": {
    "text": "RJ 1000",
    "color": "#0f766e"
  },
  "status": {
    "label": "+8 min",
    "tone": "warning"
  },
  "journey": {
    "calls": [
      {
        "name": "Ostrava hlavní nádraží",
        "departure": "2026-11-04T05:05:00+01:00",
        "scheduledDeparture": "2026-11-04T05:05:00+01:00",
        "platform": "2",
        "state": "passed"
      },
      {
        "name": "Pardubice hlavní nádraží",
        "arrival": "2026-11-04T07:30:00+01:00",
        "departure": "2026-11-04T07:38:00+01:00",
        "scheduledArrival": "2026-11-04T07:22:00+01:00",
        "scheduledDeparture": "2026-11-04T07:30:00+01:00",
        "platform": "3",
        "state": "current"
      }
    ]
  },
  "highlight": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "LineString",
          "coordinates": [
            [
              15.77,
              50.03
            ],
            [
              14.43,
              50.08
            ],
            [
              14.6,
              50.07
            ]
          ]
        },
        "properties": {
          "role": "upcoming"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            15.77,
            50.03
          ]
        },
        "properties": {
          "role": "current",
          "name": "Pardubice hlavní nádraží"
        }
      }
    ]
  },
  "color": "#0f766e",
  "generated": "2026-11-04T07:35:00Z",
  "ttl": 30
}
```

Pełny przykład: [detail-jizda.json](https://datovamapa.cz/priklady/detail-jizda.json).

## Transport {#doprava}

Zbiory z bieżącymi pozycjami pojazdów transportu publicznego (pociągi, autobusy, tramwaje, metro…) oznacz `"profile": "transit_vehicles"`. Portal pokaże je wtedy we wspólnej warstwie „Transport na żywo”: wszystkie tym samym stylem (kształt według rodzaju, kolor według opóźnienia), z jedną legendą, filtrem według rodzaju transportu, opóźnienia i przewoźnika oraz z wyszukiwaniem kursu. Użytkownik wybiera więc rodzaj transportu, a nie źródło danych.

Zbiór z profilem musi mieć `live`, prezentację `circle` i obiekty jako punkty z `feature.dm.transit`. Walidator zgłasza brak `live` (`transit_missing_live`), inną prezentację (`transit_not_circle`), obiekt bez `dm.transit` (`transit_missing_properties`) i obiekt, który nie jest punktem (`transit_not_point`).

| Pole `dm.transit` | Wymagane | Opis |
|---|---|---|
| `mode` | tak | `rail`, `bus`, `tram`, `metro`, `trolleybus`, `ferry`, `funicular`, `other` |
| `label` | tak | Oznaczenie, którego szukają ludzie: pociąg (`R 1234`), linia (`188`) |
| `line` | nie | Linia, gdy różni się od oznaczenia (`S2`) |
| `headsign`, `operator` | nie | Cel kursu, przewoźnik |
| `delay_min` | nie | Opóźnienie w pełnych minutach, ujemne = przed czasem |
| `delay_band` | tak | `on_time` do 4 min, `minor` 5 do 14, `medium` 15 do 29, `major` 30 do 59, `extreme` 60 i więcej, `unknown` bez danych |
| `bearing` | nie | Kierunek jazdy w stopniach od północy |
| `trip_ref` | nie | Stały klucz kursu (ten sam przy kolejnych odświeżeniach); taki sam jak `id` obiektu, jeśli zbiór oferuje szczegóły kursu |
| `observed_at` | tak | Kiedy zmierzono pozycję (ISO 8601) |

Każdy pojazd ma być na mapie tylko raz. Gdy te same pojazdy zgłasza kilka źródeł, niech wydaje je tylko jeden zbiór. Właściwości w `properties` (opisy dla ludzi w języku kraju) pozostają, `dm.transit` to neutralna część dla portalu.

```json data
{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "id": "1234|20261104",
    "geometry": { "type": "Point", "coordinates": [14.4352, 50.0833] },
    "properties": { "vlak": "R 1234", "cil": "Brno hl.n.", "zpozdeni_min": 6 },
    "dm": {
      "transit": {
        "mode": "rail", "label": "R 1234", "headsign": "Brno hl.n.", "operator": "České dráhy",
        "delay_min": 6, "delay_band": "minor", "bearing": 135, "trip_ref": "1234|20261104",
        "observed_at": "2026-11-04T07:35:10Z"
      }
    }
  }]
}
```
Pełny przykład: [data-doprava.json](https://datovamapa.cz/priklady/data-doprava.json).

## Cache {#cache}

- Portal przechowuje odpowiedzi przez czas `min(cache.ttl, dm.ttl)`, domyślnie 300 s. Manifesty 10 min.
- Po upływie tego czasu przechowuje wpis jeszcze 24 h jako kopię zapasową: gdy źródło nie odpowiada, pokazuje ostatnie dane z ostrzeżeniem.
- `cache.store: false` – dostawca nie zgadza się na trwałe zapisanie danych w warstwie danych portalu (krótkotrwałe buforowanie odpowiedzi według `ttl` obowiązuje nadal).
- `live: { interval }` – dane na żywo. Włączony zbiór w otwartej mapie sam pobiera się ponownie co `interval` sekund (10 do 3600), bez odświeżania strony; przy ukrytej karcie odświeżanie się zatrzymuje. Interwał krótszy niż `cache.ttl` walidator zgłasza (`live_interval_below_ttl`), bo mapa pytałaby częściej, niż zmieniają się dane. Portal oznacza zbiór z `live` jako działający na żywo także bez „(na żywo)” w nazwie.

## Walidacja {#validace}

Zgodność z protokołem sprawdza [walidator](https://mapadanych.pl/dokumentacja/api.md#validator) (`POST /api/validate`, test na żywo `GET /api/validate?manifestUrl=…` lub narzędzia MCP `validate_manifest` i `validate_data`). Rozróżnia:

- **błędy** (`errors`) – naruszenie tego dokumentu; manifestu z błędem portal nie przyjmie, danych z błędem nie wyświetli,
- **zalecenia** (`warnings`) – dane działają, ale gorzej się je wyszukuje, wyświetla lub łączy.

Każde ustalenie ma stabilny `code` ([przegląd kodów](https://mapadanych.pl/dokumentacja/api.md#kody-nalezu)), ścieżkę `path`, a przy zaleceniach wskazówkę `hint`. Kody nie zmieniają się między wersjami minor, nowe mogą dochodzić.

## Rozwój protokołu {#vyvoj-protokolu}

- Nowe opcjonalne pola i nowe typy `presentation` / `source` = nowa wersja minor (0.2…).
- Zmiana znaczenia istniejących pól = nowa wersja major; portal przez okres przejściowy obsługuje obie.
- Kandydaci do kolejnych wersji: `symbol` (ikony), `extrusion` (3D), wymiar czasowy (`time` przy obiektach + parametr), `vector-tiles` / `pmtiles` / `ogc-features` jako źródła, stronicowanie przez `next`, agregacja dla małych przybliżeń.

---

<!-- https://mapadanych.pl/dokumentacja/api.md -->

# API portalu MapaDanych {#api-portalu-datovamapa}

Maszynowy interfejs portalu dla aplikacji i agentów AI: katalog danych, dane ze wszystkich źródeł w ujednoliconej postaci, zapytania o miejsce (co jest w punkcie i w okolicy, podsumowanie dla gminy), walidator i rejestracja dla dostawców oraz serwer MCP. Wszystko jest publiczne, bez uwierzytelniania, z CORS `*`. Formalny opis znajduje się w [OpenAPI](https://mapadanych.pl/openapi.json).

## Przegląd {#prehled}

| Metoda i ścieżka | Przeznaczenie |
|---|---|
| `GET /api/catalog` | wszyscy dostawcy i zbiory danych (JSON) |
| `GET /api/data/{provider}/{dataset}` | dane zbioru jako GeoJSON, przez cache portalu |
| `GET /api/places?query=…` | wyszukiwanie adresu, ulicy lub gminy → współrzędne |
| `GET /api/nearby?point=…` | co jest w punkcie i w okolicy, z wybranych zbiorów |
| `GET /api/summary/{provider}/{dataset}` | podsumowanie zbioru dla całego obszaru lub dla gminy |
| `GET /api/validate?manifestUrl=…` | test dostawcy na żywo |
| `POST /api/validate` | kontrola manifestu lub danych bez publikacji |
| `POST /api/registration` | rejestracja dostawcy (dane czekają na zatwierdzenie) |
| `POST /mcp` | serwer MCP (Streamable HTTP) |
| `GET /llms.txt`, `/llms-full.txt` | spis treści i cała dokumentacja dla modeli językowych |
| `GET /index.md`, `/zrodla.md`, `/dokumentacja/{slug}.md` | strony portalu w markdownie |
| `GET /schema/0.1/manifest.json`, `/schema/0.1/data.json` | JSON Schema protokołu |
| `GET /schema/0.1/provider-openapi.json` | kontrakt OpenAPI, który implementuje dostawca |
| `GET /przyklady/{plik}.json` | poprawne przykładowe manifesty i odpowiedzi |

## Katalog {#katalog}

`GET /api/catalog`

```json
{
  "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": "Indeks radonowy",
      "category": "risks",
      "categoryLabel": "Zagrożenia i ograniczenia",
      "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 zawiera wyłącznie zatwierdzone dane. Zbiorów dostawców, którzy zarejestrowali się sami i nie zostali jeszcze zatwierdzeni, w nim nie ma (zob. [Rejestracja](#registrace)).

Zbiory danych zawierają wszystkie pola z manifestu dostawcy (`description`, `fields`, `params`, `coverage`…) z wyjątkiem URL źródła – dane GeoJSON odczytuje się przez portal (`links.data`), kafelki rastrowe bezpośrednio ze źródła (`source.tiles`). Ta sama treść w postaci czytelnej dla ludzi i modeli: [zrodla.md](https://mapadanych.pl/zrodla.md).

## Dane {#data}

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

| Parametr | Kiedy | Opis |
|---|---|---|
| `bbox` | zbiory z `source.mode = "bbox"` (wymagany) | `minLon,minLat,maxLon,maxLat` w WGS84; portal wyrównuje go do kafelków |
| `zoom` | zbiory z `source.mode = "bbox"` (wymagany) | poziom przybliżenia 0–24 |
| `cursor` | opcjonalnie | kursor z `dm.next` |
| `{param}` | według `params` zbioru | wartości w formacie protokołu (`a,b`, `od,do`); niewypełnione otrzymują `default` |

Odpowiedź to GeoJSON `FeatureCollection`. Dane z `feature.dm` dostawcy są przeniesione do `properties` z przedrostkiem `__dm_` (`__dm_title`, `__dm_description`, `__dm_url`, `__dm_color`, `__dm_chart`). W zbiorach z `color.type = "trend"` portal dodaje `__dm_trend` (`roste`, `stagnuje`, `klesá`) obliczony z `dm.chart`. Metadane odpowiedzi:

```json
{ "dm": { "protocol": "0.1", "dataset": "aopk/pamatne-stromy", "generated": "…", "ttl": 86400, "total": 13, "truncated": false, "notice": null } }
```

Nagłówek `X-DM-Cache`: `hit` (z cache), `miss` (świeżo ze źródła), `stale` (źródło niedostępne, ostatnie znane dane – zob. `dm.notice`).

Błędy mają postać `{ "error": "komunikat", "code": "kod" }`: `400` nieprawidłowe zapytanie, `404` nieznany zbiór, `502` błąd źródła.

**Zbiory tylko do wyświetlania.** W przypadku kilku zbiorów zarządzanych przez portal źródło nie ma udokumentowanej licencji na dalsze rozpowszechnianie. Portal rysuje je na własnej mapie, ale danych dalej nie udostępnia: w katalogu mają puste `links.data`, a w `links.source` adres oryginalnej usługi dostawcy. Zapytanie spoza mapy portalu otrzyma `303` z nagłówkiem `Location` wskazującym tę usługę i treścią `{ "error": "…", "code": "display_only", "source": "…" }`. Tak samo odpowiada narzędzie MCP `fetch_data`.

**Szczegóły obiektu.** `GET /api/data/{dostawca}/{zbiór}/detail?id={id}` zwraca `FeatureDetail` ([protokół](https://datovamapa.cz/dokumentace/protokol.md#detail-objektu)) dla zbiorów, które mają w manifeście `detail`. Id obiektu jest w zapytaniu (nie w ścieżce), bo może zawierać `%` i `|`. Zasady jak przy danych: zbiór tylko do wyświetlania daje szczegóły tylko mapie portalu (inaczej `303`, `Cache-Control: private`), pozostałe są buforowane według `ttl` odpowiedzi. Nieznane id zwraca `404` (`unknown_detail`), zbiór bez szczegółów `404` (`no_detail`).

## Miejsce i okolica {#misto-a-okoli}

Zapytania dla asystentów AI i aplikacji, które odpowiadają na pytania o konkretne miejsce. Zwracają wartości opisane w sposób czytelny dla ludzi (etykiety i jednostki według `fields` zbioru) bez geometrii, z atrybucją i linkiem do mapy. Poradnik dla użytkowników asystentów: [Dane dla asystentów AI](https://mapadanych.pl/dokumentacja/asystenci-ai.md).

### Wyszukiwanie miejsca {#hledani-mista}

`GET /api/places?query=Floriańska 1, Kraków` (opcjonalnie `max`, domyślnie 5, maksymalnie 10)

Wyszukuje w rejestrze adresów adresy, ulice, gminy, części gmin i inne elementy terytorialne. Podaj tylko adres lub nazwę; doprecyzowań takich jak powiat czy „koło Zakopanego” usługa nie rozumie. `municipality` to gmina, w której miejsce leży (`name`, `district`, `region` i kod TERYT gminy `code`) – dla niej [podsumowanie](#souhrn) zwraca dane za całą gminę. Dla miejsc poza miastami powyżej 10 000 mieszkańców jest dodatkowo `near` – najbliższe takie miasto i odległość w km; według obu pól rozróżnia się miejsca o tej samej nazwie.

```json
{
  "query": "Floriańska 1, Kraków",
  "count": 1,
  "places": [{ "name": "Floriańska 1, 31-019 Kraków", "type": "adres", "point": [19.9393, 50.0626], "municipality": { "slug": "krakow", "code": "1261011", "name": "Kraków", "district": "Kraków", "region": "Województwo małopolskie" } }],
  "attribution": "© źródło rejestru adresów"
}
```

### Co jest w punkcie i w okolicy {#co-je-v-bode-a-okoli}

`GET /api/nearby`

| Parametr | Opis |
|---|---|
| `point` | `lon,lat` w WGS84 |
| `place` | zamiast `point`: adres lub nazwa, używany jest pierwszy wynik wyszukiwania miejsca |
| `radius` | promień okolicy w metrach, domyślnie 500, maksymalnie 20 000 |
| `datasets` | klucze `provider/dataset` rozdzielone przecinkami, maksymalnie 12 |
| `purpose` | zamiast `datasets`: zbiory o tym przeznaczeniu (`useCases`), które obejmują punkt |
| `search` | zamiast `datasets`: zbiory według zgodności z tekstem, np. `zagrożenia dla budowy` |
| `max` | maksymalnie obiektów na zbiór, domyślnie 5, maksymalnie 50 |
| `{provider}/{dataset}.{param}` | parametr zbioru, tak samo jak w [linku do mapy](#odkaz-na-mapu) |

Jeden z parametrów `datasets`, `purpose`, `search` jest wymagany. Automatyczny wybór bierze tylko zbiory, które potrafią odpowiedzieć dla punktu: najpierw zagrożenia i ograniczenia, mapy podkładowe na końcu. Zbiory ponad limit zwraca w `skipped`.

- **Zbiory GeoJSON:** obiekty w odległości do `radius` uporządkowane od najbliższego. `distance` jest w metrach, 0 = punkt leży wewnątrz powierzchni (np. gmina w kartogramie). `count` to liczba obiektów w okolicy. Zbiory wczytywane tylko przy dużym przybliżeniu zmniejszają okolicę (`radius`, `notice`). W przypadku zbiorów pełnych (`mode: full`), które w okolicy nic nie mają, zwraca przynajmniej najbliższy obiekt (np. stację pomiarową).
- **Zbiory rastrowe:** portal pyta źródło bezpośrednio o punkt. Zapytanie wyprowadza z szablonu kafelków: WMS `GetMap` → `GetFeatureInfo`, ArcGIS `MapServer/export` → `identify`, `ImageServer/exportImage` → `identify` z tabelą klas rastra. Wartości są atrybutami źródła (nazwy pól takie, jakie zwraca źródło). W interpretacji kodów pomogą `description` i `legend`.

| `status` | Znaczenie |
|---|---|
| `ok` | zapytanie się powiodło; puste `hits` = w okolicy / w punkcie nic nie ma (np. poza obszarem zagrożenia powodziowego) |
| `unavailable` | zbiór nie udostępnia wartości w punkcie (kafelki są tylko obrazem) lub punkt leży poza zasięgiem |
| `error` | źródło zawiodło (`error`, `code`) |

```json
{
  "place": { "name": "Floriańska 1, 31-019 Kraków", "type": "adres", "point": [19.9393, 50.0626] },
  "point": [19.9393, 50.0626],
  "radius": 500,
  "generated": "2026-10-06T16:00:00.000Z",
  "results": [
    {
      "dataset": "cgs/radon",
      "title": "Indeks radonowy",
      "provider": "Česká geologická služba",
      "attribution": "© Česká geologická služba",
      "status": "ok",
      "hits": [{ "title": "Indeks radonowy", "distance": 0, "values": [{ "label": "radonovériziko", "value": "přechodný" }, { "label": "stupeňradonovéhoindexu", "value": "2" }] }]
    },
    {
      "dataset": "npu/kulturni-pamatky",
      "title": "Zabytki kultury",
      "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": "fabryka Breitfeld-Daněk",
          "distance": 91,
          "values": [{ "label": "Numer rejestru ÚSKP", "value": "105958" }, { "label": "Stan ochrony", "value": "pod ochroną konserwatorską" }],
          "url": "https://pamatkovykatalog.cz/x-14624751"
        }
      ]
    }
  ],
  "map": "https://mapadanych.pl/?d=cgs/radon&d=npu/kulturni-pamatky#15/50.0626/19.9393"
}
```

### Podsumowanie {#souhrn}

`GET /api/summary/{provider}/{dataset}?municipality=Kraków` (pozostałe parametry zapytania są parametrami zbioru)

Podsumowanie zbioru GeoJSON dla całego obszaru albo, z `municipality`, tylko dla gminy – dowolnej gminy w Polsce: `count`, `categories` (liczby według kategorii koloru), `rankings` (najwyższe i najniższe wartości), a w przypadku kartogramu `own` – wartości powierzchni, w której gmina leży. Są to te same liczby, które pokazuje strona zbioru. Zbiory wczytywane tylko przy dużym przybliżeniu mają podsumowanie wyłącznie dla gminy. Zbiory rastrowe podsumowania nie mają.

`municipality` to nazwa („Kraków”), nazwa z powiatem lub województwem („Michałowice (powiat krakowski)”), kod TERYT gminy („1261011”, zwraca go [wyszukiwanie miejsca](#hledani-mista) w `municipality.code`) lub adres jej strony przeglądowej („malopolskie/michalowice-krakowski”). Sama nazwa, którą nosi kilka gmin, kończy się błędem `ambiguous_place` z listą tych gmin, ich powiatów i kodów.

## Walidator {#validator}

Narzędzie dla dostawców i ich agentów AI. Zawsze zwraca HTTP 200 i raport:

```json
{
  "valid": false,
  "summary": "Manifest nie jest poprawny: 1 błąd, 2 zalecenia.",
  "errors": [{ "path": "datasets[0].source.tiles[0]", "code": "raster_without_template", "message": "Szablon kafelków nie zawiera {z}/{x}/{y} ani {bbox-epsg-3857}." }],
  "warnings": [{ "path": "datasets[0].keywords", "code": "missing_keywords", "message": "Zbiór nie ma słów kluczowych.", "hint": "Dodaj 5–15 słów…" }]
}
```

- `POST /api/validate` z treścią:
  - manifest (obiekt z `datasets`) lub `{ "manifest": … }` – kontrola statyczna,
  - GeoJSON `FeatureCollection` lub `{ "data": …, "dataset": … }` – kontrola danych; z `dataset` (obiekt zbioru z manifestu) również zgodność z manifestem,
  - `{ "manifestUrl": "https://…" }` – test na żywo.
- `GET /api/validate?manifestUrl=https://…` – test na żywo: pobiera manifest, sprawdza go i do każdego zbioru wysyła zapytanie testowe tak jak portal (przy `bbox` na środek `coverage.bbox`, zoom 12 lub `coverage.minZoom`; przy rastrze jeden kafelek). Raport zawiera dodatkowo `provider` i `datasets[]` z `request`, `durationMs`, `featureCount`, `errors`, `warnings`.

## Rejestracja {#registrace}

`POST /api/registration` z treścią `{ "manifestUrl": "https://…" }`. Portal sprawdza manifest testem na żywo (tak jak walidator). Jeśli test przejdzie, rejestruje dostawcę wśród niezatwierdzonych danych:

- Dane są dostępne przez `/api/data/…` i na stronach zbiorów `/mapa/{provider}/{dataset}`. Strona najpierw pokazuje ostrzeżenie, że dane wgrała strona trzecia i operator ich nie zatwierdził. Dane wczytuje na mapę dopiero po potwierdzeniu. Strona ma `noindex`.
- Do katalogu, wyszukiwania, `llms.txt`, narzędzia MCP `catalog` i na strony gmin dane trafiają dopiero po zatwierdzeniu przez operatora.
- Zatwierdzenie dotyczy odcisku (SHA-256) treści manifestu. Po zmianie manifestu dostawca jest znowu niezatwierdzony, dopóki operator nie zatwierdzi go ponownie.
- Przegląd niezatwierdzonych dostawców: [/niezatwierdzone-dane](https://mapadanych.pl/niezatwierdzone-dane).

```json
{
  "registered": true,
  "status": "pending_review",
  "message": "Zarejestrowano. …",
  "provider": { "id": "gmina-przyklad", "name": "Gmina Przykład" },
  "links": { "review": "/niezatwierdzone-dane#gmina-przyklad", "datasets": ["/mapa/gmina-przyklad/lawki"] },
  "check": { "summary": "Dostawca jest poprawny bez zastrzeżeń.", "warnings": [] }
}
```

| HTTP | `code` | Znaczenie |
|---|---|---|
| 201 | – | zarejestrowano, czeka na zatwierdzenie |
| 200 | – | już zarejestrowano; `status` to `pending_review` lub `approved` |
| 400 | `invalid_input`, `invalid_url` | brak `manifestUrl` lub jest nieprawidłowy |
| 403 | `rejected` | operator odrzucił rejestrację |
| 409 | `id_taken`, `url_registered` | `provider.id` już jest w portalu / URL jest zarejestrowany pod innym id |
| 422 | `manifest_rejected` | test na żywo nie przeszedł; raport jest w `check` |
| 429 | `too_many_requests`, `queue_full` | więcej niż 5 prób na minutę z jednego adresu / na zatwierdzenie czeka ponad 100 dostawców |
| 503 | `registration_unavailable` | rejestracja obecnie nie działa |

## Serwer MCP {#mcp-server}

Endpoint `https://mapadanych.pl/mcp`, transport Streamable HTTP (bezstanowy, odpowiedzi JSON), bez uwierzytelniania.

| Narzędzie | Wejście | Wyjście |
|---|---|---|
| `documentation` | `topic`: `ai-agents`, `ai-assistants`, `protocol`, `providers`, `api`, `about` | markdown dokumentu |
| `schema` | `type`: `manifest`, `data`, `provider-openapi` | JSON Schema / OpenAPI |
| `example` | `name`: `manifest-minimal`, `manifest-complete`, `data-points`, `data-polygons` | poprawny przykładowy JSON |
| `validate_manifest` | `manifest` (obiekt) lub `manifestUrl` (test na żywo) | raport walidatora |
| `validate_data` | `data`, opcjonalnie `dataset` | raport walidatora |
| `register_provider` | `manifestUrl` | wynik [rejestracji](#registrace) |
| `catalog` | opcjonalnie `search` (dowolny tekst), `point` (`[lon, lat]`) | zbiory danych w portalu, uporządkowane według zgodności; `pointQuery` = zbiór odpowie na `nearby` |
| `find_place` | `query`, `maxResults` | jak [wyszukiwanie miejsca](#hledani-mista) |
| `nearby` | `point` lub `place`; `datasets`, `purpose` lub `search`; `radius`, `maxFeatures`, `params` (`{ "provider/dataset": { "param": "wartość" } }`) | jak [co jest w punkcie i w okolicy](#co-je-v-bode-a-okoli) |
| `summary` | `dataset`, opcjonalnie `municipality`, `params` | jak [podsumowanie](#souhrn) |
| `fetch_data` | `dataset` (`provider/dataset`), `bbox` lub `municipality`, `zoom`, `params`, `maxFeatures` | GeoJSON (skrócony do `maxFeatures`) |

Połączenie:

```bash
claude mcp add --transport http datovamapa https://mapadanych.pl/mcp
```

```json
{ "mcpServers": { "datovamapa": { "type": "http", "url": "https://mapadanych.pl/mcp" } } }
```

## Link do mapy {#odkaz-na-mapu}

`https://mapadanych.pl/?d={provider}/{dataset}&d=…&{provider}/{dataset}.{param}={wartość}#{zoom}/{lat}/{lon}`

Każdy zbiór ma też własną stronę z mapą i opisem: `https://mapadanych.pl/mapa/{provider}/{dataset}`, ogólnokrajowe zbiory GeoJSON także dla gmin powyżej 10 000 mieszkańców: `https://mapadanych.pl/mapa/{provider}/{dataset}/{gmina}` (np. [/mapa/chmu/kvalita-ovzdusi/ostrava](https://mapadanych.pl/mapa/chmu/kvalita-ovzdusi/ostrava)). Link do strony zbioru jest w katalogu w `links.map`. Na stronie zbioru (i mapy zestawionej `/mapy/{slug}`) do `?d=…` zapisuje się tylko różnicę względem domyślnego wyboru: bez `d` obowiązują zbiory strony, `d` wymienia cały wybór (`?d=` = nic nie jest włączone), a parametr podaje się tylko wtedy, gdy różni się od domyślnego.

Przykład – wypadki drogowe w Brnie łącznie za lata 2019–2023: [/?d=brno/dopravni-nehody&brno/dopravni-nehody.obdobi=2019,2023#13/49.195/16.608](https://mapadanych.pl/?d=brno/dopravni-nehody&brno/dopravni-nehody.obdobi=2019,2023#13/49.195/16.608)

## Kody ustaleń {#kody-nalezu}

Stabilne kody błędów (`errors`) i zaleceń (`warnings`) walidatora i proxy.

### Manifest {#manifest}

| Kod | Poziom | Znaczenie |
|---|---|---|
| `schema_*` | błąd | naruszenie JSON Schema (`schema_invalid_type`, `schema_too_small`, `schema_invalid_format`, `schema_invalid_value`, `schema_custom`…), `path` wskazuje miejsce |
| `unsupported_version` | błąd | inna wersja główna protokołu |
| `raster_without_template` | błąd | URL kafelków bez `{z}/{x}/{y}` i bez `{bbox-epsg-3857}` |
| `geojson_with_raster_presentation` | błąd | źródło GeoJSON z `presentation.type: "raster"` |
| `param_without_options` | błąd | `enum` / `multi-enum` bez `options` |
| `invalid_default` | błąd | `default` parametru nie odpowiada typowi lub opcjom |
| `time_param_missing` | błąd | `temporal.param` wskazuje parametr, którego nie ma w `params` |
| `time_param_type` | błąd | parametr czasowy nie jest typu `range` ani `date-range` |
| `time_param_no_range` | zalecenie | parametr czasowy typu `range` nie ma `min` i `max` |
| `live_interval_below_ttl` | zalecenie | `live.interval` jest krótszy niż `cache.ttl`, mapa pytałaby częściej, niż zmieniają się dane |
| `unknown_presentation_type` | zalecenie | portal nie zna typu, rysuje `auto` |
| `raster_without_raster_presentation` | zalecenie | raster jest zawsze rysowany jako `raster` |
| `missing_description`, `missing_keywords`, `missing_use_cases` | zalecenie | zbiór trudniej znajdą ludzie i asystent |
| `missing_category`, `unknown_category` | zalecenie | zbiór trafi do kategorii „Inne” |
| `missing_field` | zalecenie | szczegóły obiektu pokażą surowe nazwy właściwości |
| `detail_url_without_id` | błąd | szablon `detail.url` nie zawiera `{id}` |
| `detail_url_not_https` | błąd | szablon `detail.url` nie jest https ani adresem względnym |
| `detail_without_primary_field` | zalecenie | zbiór ze szczegółami nie ma właściwości z `primary: true` (tytuł okna, zanim wczytają się szczegóły) |
| `detail_highlight_too_large` | zalecenie | `highlight` w szczegółach ma ponad 200 kB |
| `transit_missing_live` | błąd | zbiór z profilem `transit_vehicles` nie ma `live` |
| `transit_not_circle` | błąd | zbiór z profilem `transit_vehicles` nie ma prezentacji `circle` |
| `transit_missing_properties` | błąd | pojazd zbioru z profilem `transit_vehicles` nie ma `dm.transit` |
| `transit_not_point` | błąd | pojazd zbioru z profilem `transit_vehicles` nie jest punktem |
| `field_not_described`, `field_not_number` | zalecenie | prezentacja odwołuje się do właściwości spoza `fields` / o nieliczbowym typie |
| `bbox_unbounded` | zalecenie | zbiór `bbox` bez `coverage.minZoom` i `maxFeatures` |
| `missing_coverage` | zalecenie | zbiór `bbox` bez `coverage.bbox` |
| `missing_license`, `missing_website` | zalecenie | brak licencji / strony internetowej dostawcy |

### Dane {#data}

| Kod | Poziom | Znaczenie |
|---|---|---|
| `coordinates_out_of_range` | błąd | współrzędne poza WGS84 (zwykle nieprzeliczony PUWG 1992, EPSG:2180) |
| `unclosed_polygon` | błąd | pierścień wielokąta nie jest zamknięty |
| `too_many_features` | zalecenie | więcej obiektów niż `limit` / 5 000 |
| `missing_time_series` | zalecenie | zbiór ma `temporal.param`, odpowiedź nie zawiera `dm.timeline` ani `dm.chart` |
| `missing_trend_chart` | zalecenie | zbiór koloruje według wartości liczbowej i wybiera okres parametrem, ale obiekty nie zawierają `dm.chart` |
| `trend_without_chart` | zalecenie | zbiór jest kolorowany według trendu, niektóre obiekty nie mają `dm.chart` (pozostaną szare) |
| `swapped_coordinates` | zalecenie | współrzędne prawdopodobnie w kolejności `[lat, lon]` |
| `outside_coverage` | zalecenie | większość obiektów poza `coverage.bbox` |
| `geometry_presentation_mismatch` | zalecenie | np. powierzchnie przy `circle` |
| `field_missing_in_data`, `missing_presentation_property` | zalecenie | brak w danych właściwości z manifestu |
| `missing_id` | zalecenie | obiekty bez `id` |
| `empty_geometry` | zalecenie | obiekty z `geometry: null` są pomijane |

### Test na żywo i proxy {#zivy-test-a-proxy}

| Kod | Znaczenie |
|---|---|
| `invalid_url`, `https_required` | nieprawidłowy URL / źródło nie działa na HTTPS |
| `source_unreachable`, `timeout`, `http_error` | źródło nie odpowiada, nie zdążyło w 10 s, zwróciło błąd HTTP |
| `invalid_json`, `empty_body`, `response_too_large` | odpowiedź nie jest JSON-em / jest pusta / ma ponad 15 MB |
| `invalid_gtfs_rt` | źródło GTFS Realtime (protobuf) zwróciło uszkodzone dane |
| `invalid_manifest`, `id_mismatch` | manifest zarejestrowanego dostawcy nie przeszedł kontroli / ma inne `provider.id` |
| `registration_unavailable`, `too_many_requests`, `queue_full`, `manifest_rejected`, `id_taken`, `url_registered`, `rejected` | błędy [rejestracji](#registrace) |
| `data_schema_mismatch` | dane ze źródła nie odpowiadają schematowi |
| `invalid_id`, `no_detail`, `unknown_detail` | szczegóły obiektu: brak id / zbiór nie ma szczegółów / obiekt o tym id nie istnieje (`404`) |
| `detail_schema_mismatch` | szczegóły ze źródła nie odpowiadają schematowi `FeatureDetail` |
| `empty_response`, `slow_response` | zapytanie testowe zwróciło 0 obiektów / trwało ponad 3 s |
| `tile_http_error`, `tile_not_image`, `tile_unreachable` | testowy kafelek rastrowy zawiódł |
| `data_not_ready` | portal nie ma jeszcze wstępnie przetworzonych danych zbioru (przygotowuje je węzeł danych), spróbuj później |
| `source_error` | inny błąd w komunikacji ze źródłem (szczegóły w `message`) |
| `invalid_query`, `unknown_dataset`, `raster_dataset`, `invalid_input`, `internal_error` | błędy zapytania do portalu |
| `display_only` | portal tylko wyświetla zbiór, dane udostępnia oryginalna usługa (`source`) |
| `missing_place`, `unknown_place` | zapytanie o miejsce bez punktu i bez miejsca / nie udało się znaleźć miejsca (adresu, gminy) |
| `geocoding_unavailable` | wyszukiwania adresów i miejsc w danym kraju portal jeszcze nie ma (HTTP 501) |
| `ambiguous_place` | nazwę gminy nosi kilka gmin – komunikat wymienia je z powiatem i kodem |
| `missing_dataset_selection` | zapytanie o okolicę bez `datasets`, `purpose` i bez `search` |
| `summary_requires_place` | zbiór można wczytać tylko po przybliżeniu, nie ma podsumowania dla całego obszaru – podaj gminę |
| `unknown_schema`, `unknown_example` | nieistniejący schemat / przykład (odpowiedź zawiera listę `available`) |

---

<!-- https://mapadanych.pl/dokumentacja/o-projekcie.md -->

# MapaDanych – wizja {#datovamapa-vize}

Data: 2026-10-06 (zastępuje pierwotny kontekst z 2026-08, który znajduje się w `docs/archiv/`)

## Czym jest MapaDanych {#co-je-datovamapa}

MapaDanych to **otwarty interfejs do wizualizacji danych na mapie**. Definiuje otwarty schemat (protokół), dzięki któremu każdy może pokazać na mapie dowolne dane – punkty, linie, powierzchnie, gęstości, warstwy rastrowe.

Zasada działania:

1. Dostawca danych publikuje **manifest** (opis siebie i swoich zbiorów danych) oraz **endpoint danych** zgodny z protokołem MapaDanych.
2. Dostawca rejestruje manifest; po zatwierdzeniu przez operatora zbiory pojawiają się w katalogu.
3. Gdy użytkownik włączy zbiór, portal odpytuje źródło (dla bieżącego wycinka mapy i ustawionych filtrów), weryfikuje odpowiedź, zapisuje ją w cache i rysuje zgodnie z opisem z manifestu.

Portal nie jest właścicielem danych; pośredniczy w ich udostępnianiu i zawsze podaje źródło. Operatorem portalu jest [vrealmatic.com](https://vrealmatic.com/web).

## Korzyści {#prinos}

**Dla użytkowników:** na jednej mapie łączą dane z dowolnych źródeł – bez przełączania się między dziesiątkami portali mapowych.

**Dla dostawców:**

- nie muszą zajmować się mapą, stylami ani serwerem map – wystarczy endpoint JSON,
- stają się częścią otwartego portalu danych, a ich dane spotykają się z danymi innych,
- są widocznie wskazani jako źródło (przy danych na mapie, w szczegółach obiektu, w przeglądzie źródeł).

## Dane przygotowują agenci AI {#data-pripravuji-ai-agenti}

Zakładamy, że dane u dostawców będą przygotowywać głównie agenci AI (na polecenie człowieka, do którego dane należą). Dlatego cały portal jest zbudowany jako „AI friendly”:

- **Wszystko jest w markdownie.** Każda strona dokumentacji ma wersję markdown (`/dokumentacja/{slug}.md`), strona główna `/index.md`, katalog `/zrodla.md`; spis treści `/llms.txt` i cała dokumentacja w jednym pliku `/llms-full.txt`. Źródłem prawdy są pliki w `docs/`, HTML jest z nich generowany.
- **Instrukcja dla agentów** z procedurą, tabelami decyzyjnymi, szablonami kodu, zasadami (dane osobowe, licencje) i kryteriami ukończenia pracy.
- **Schematy maszynowe** generowane z jednego źródła: JSON Schema manifestu i danych, kontrakt OpenAPI dostawcy (agent może z niego wygenerować serwer) i OpenAPI portalu.
- **Walidator z informacją zwrotną**: stabilne kody wyników, dokładne ścieżki i wskazówki, jak naprawić błąd; test na żywo całego dostawcy. Agent iteruje, dopóki nie uzyska `valid: true`.
- **Serwer MCP** `/mcp`: dokumentacja, schematy, przykłady, walidacja, katalog i dane jako narzędzia.
- **Sprawdzone przykłady**: każdy przykład w dokumentacji przechodzi przez walidator (`npm run check:docs`), aby agent nie skopiował błędu.
- **Pola ułatwiające wyszukiwanie**: `keywords`, `useCases`, `description`, `fields` – dzięki nim dane znajdą zarówno ludzie, jak i asystent portalu.

Dane z portalu czytają też asystenci AI zwykłych ludzi i firm. Przez serwer MCP lub HTTP API znajdują miejsce (rejestr adresów), pytają wybrane zbiory, co jest w danym punkcie i w okolicy (również mapy rastrowe, takie jak powodzie, radon czy hałas), i otrzymują podsumowanie dla gminy. Sami interpretują dane i podają źródło. Instrukcja: [Dane dla asystentów AI](https://mapadanych.pl/dokumentacja/asystenci-ai.md).

## Zasady {#principy}

- **Otwarty protokół.** Schemat jest publiczny (`/schema/0.1/manifest.json`, `/schema/0.1/data.json`), oparty na GeoJSON (RFC 7946). Prawie wszystko jest opcjonalne, obowiązkowe jest tylko niewielkie minimum.
- **Zamiar, nie biblioteka.** Dostawca opisuje, *co* chce pokazać (punkty według kategorii, kartogram według wartości…), a nie konkretne ustawienia biblioteki mapowej. Portal może zmieniać sposób rysowania bez wpływu na dostawcę.
- **Zgodność w przód.** Nieznane pola są ignorowane, nieznany typ wizualizacji jest rysowany stylem domyślnym. Protokół może więc rosnąć, nie psując istniejących źródeł.
- **Prosta strona główna.** Tylko mapa i logo. Po najechaniu myszą / kliknięciu otwiera się wybór danych. Żadnych dodatkowych paneli.
- **Strony wejściowe dla konkretnych danych.** Kto szuka konkretnego wskaźnika, trafia z wyszukiwarki na stronę zbioru (`/mapa/{provider}/{dataset}`), zbioru dla gminy lub gotowej mapy (`/mapy/{slug}`): ta sama mapa z domyślnie włączonymi danymi i opisem z podsumowaniem danych. Kolejne warstwy dodaje do mapy tak samo jak na stronie głównej.
- **Bezpieczeństwo.** Dane dostawców nigdy nie są wstawiane jako HTML, proxy odpytuje tylko zarejestrowane źródła, z limitami czasu i rozmiaru.

## Strona główna {#hlavni-stranka}

- Mapa na całym ekranie i logo w lewym górnym rogu. Mapa otwiera się z widokiem na całą Polskę.
- **Wprowadzenie.** Kto wchodzi bez wyboru danych i bez odnośnika do miejsca, tego mapa przy ładowaniu poprosi w przeglądarce o lokalizację, przeniesie go w jego okolicę, a obok mapy otworzy się okno powitalne „Twoja okolica w danych” – szybki start: asystent (w przygotowaniu) z szybkimi opcjami, czyli gotowymi mapami na jedno kliknięcie, oraz odnośnikami do aktualnych danych. Poszczególne warstwy włącza się w katalogu („Cały katalog”). Kto nie udostępni lokalizacji albo jest poza Polską, dostaje wprowadzenie dla całej Polski. Odnośnik z wyborem danych pomija wprowadzenie; wraca ono jednak zawsze, gdy na mapie nic nie ma.
- Dokładną lokalizację użytkownik wyświetla przyciskiem „Moja okolica” w prawym górnym rogu obok sterowania mapą – przeglądarka pyta dopiero po kliknięciu; kto udostępnił lokalizację wcześniej, tego mapa od razu pokaże w jego okolicy (a wprowadzenie użyje tej lokalizacji).
- Najechanie myszą na logo (albo kliknięcie / dotknięcie) otwiera duże okno wyboru (ponad 80 % szerokości): po lewej **katalog** w postaci kart według kategorii z wyszukiwaniem, po prawej **Na mapie** – włączone warstwy ze stanem, legendą i filtrami. U góry jest zapowiedź przyszłego asystenta – na razie nieaktywna. Kliknięcie lub praca w oknie przypina je, zamyka się krzyżykiem, klawiszem Esc lub kliknięciem poza oknem.
- Wybór zapisuje się w URL, odnośnik można udostępnić.

### Polecenie w języku naturalnym (przyszłość) {#zadani-v-prirozenem-jazyce-budoucnost}

Cel: użytkownik napisze np. *„Chcę budować dom w gminie Wieliczka, pokaż mi wszystkie dane istotne dla mojego celu”*, a portal:

1. zrozumie miejsce (geokodowanie gminy / adresu / działki) i przesunie mapę,
2. zrozumie cel (budowa) i wybierze odpowiednie zbiory według `useCases`, `keywords` i opisów w manifestach,
3. ewentualnie ustawi filtry i podsumuje, co widzi w danych.

W oknie jest na razie tylko nieaktywna zapowiedź. Kroki 1–3 potrafi już jednak zewnętrzny asystent AI przez MCP: `find_place` (geokodowanie z rejestru adresów), `nearby` (wybór zbiorów według celu lub tekstu i zapytanie o punkt) oraz `summary`. Wyboru zbiorów według słów kluczowych i celów (`src/lib/search.ts`) używa też wyszukiwanie w katalogu i narzędzie MCP `catalog`. Dlatego manifesty mają pola `keywords` i `useCases` – przygotowują dane dla asystenta.

## Cache i własna warstwa danych {#cache-a-vlastni-datova-vrstva}

Na początku źródłem danych są zewnętrzne API dostawców. Portal trzyma odpowiedzi w cache (według `cache.ttl`), aby nie obciążać źródeł i aby mapa była szybka; przy awarii źródła może przez krótki czas pokazywać ostatnie znane dane.

W warunkach dla dostawców zastrzegamy sobie, że w interesie **przyspieszenia, odciążenia źródeł, trwałości, lepszej kombinatoryki, łączenia kontekstów i pracy z dużymi danymi** możemy przechowywać dane we własnym cache / własnej warstwie danych. Dostawca może to wyłączyć dla danego zbioru (`cache.store: false`).

## Oceny autorskie (kolejna wersja) {#autorska-hodnoceni-dalsi-verze}

Propozycja, jeszcze niezaimplementowana. Warstwa dla ludzi z własnym zdaniem i publicznością – blogerów, recenzentów, klubów – którzy chcą pokazać oceny miejsc: „Kawiarnie według …”, „Trasy rowerowe według …”, „Place zabaw według …”. Każde miejsce ma ocenę, krótki werdykt i odnośnik do artykułu.

Dziś da się to zrobić tylko ogólnie: autor publikuje własny manifest i GeoJSON z polem liczbowym i koloruje punkty według wartości. Portal nie wie jednak, że chodzi o ocenę, a autor musi sam hostować dane.

Propozycja:

- **Hostujemy my.** Autor wgrywa CSV lub GeoJSON albo wyklikuje punkty na mapie. Dane przechowuje portal (D1 / R2), autor nie potrzebuje własnej strony.
- **Ocena jako pojęcie protokołu.** Typ wizualizacji `rating` i pola obiektu `rating`, `ratingMax` (domyślnie 5), `review` (krótki werdykt), `url` (artykuł) oraz `visited` (data wizyty). Portal pokaże gwiazdki w szczegółach, zaproponuje filtr „od N gwiazdek” i sam wyprowadzi legendę. Z typu może korzystać także dostawca z własnym manifestem.
- **Autor jest widoczny.** Ocena to opinia konkretnej osoby, a nie informacja portalu. Imię i nazwisko oraz odnośnik do autora są przy warstwie i w szczegółach każdego miejsca.
- **Zatwierdzanie.** Warstwa jest poza katalogiem, dopóki operator jej nie zatwierdzi, tak samo jak przy [samodzielnej rejestracji](https://mapadanych.pl/dokumentacja/dla-dostawcow.md#5-registrace).

Otwarte pytania:

- **Konta.** Portal nie ma dziś kont użytkowników. Wgrywanie wymaga logowania (np. linkiem w e-mailu) i ochrony przed nadużyciami.
- **Zatwierdzanie zmian.** Autor będzie stale uzupełniał dane. Zatwierdzać autora raz, czy każdą zmianę?
- **Wolne punkty czy istniejące miejsca?** Powiązanie z istniejącym miejscem (np. lokalem z OpenStreetMap) pozwoli porównać kilku autorów przy jednym miejscu, ale jest znacznie bardziej złożone.
- **Podsumowania.** Średnia z wielu autorów zbliża się do serwisów z recenzjami i otwiera ryzyko manipulacji (zmyśleni autorzy). Na początek tylko warstwy obok siebie.
- **Prawo.** Negatywna ocena wymienionego z nazwy lokalu może naruszać dobra osobiste osoby prawnej (art. 43 w zw. z art. 23 i 24 Kodeksu cywilnego). Potrzebne są warunki „autor odpowiada za swoje treści”, zgłaszanie miejsc i szybkie usuwanie. Ocenia się miejsca, nie osoby prywatne.

## Plan {#plan}

1. **v0.1 (gotowe):** protokół (manifest + odpowiedź GeoJSON), katalog, proxy z cache, wizualizacje circle / heatmap / line / fill / raster / auto, filtry, szczegóły obiektu, przegląd źródeł, przykładowy dostawca; dokumentacja w markdownie, llms.txt, walidator, serwer MCP, OpenAPI.
2. **Rejestracja dostawców:** samoobsługowa rejestracja z zatwierdzaniem jest gotowa (formularz, API, MCP); pozostaje monitorowanie dostępności źródeł.
3. **Asystent:** dla zewnętrznych asystentów AI gotowe (MCP i API: geokodowanie z rejestru adresów, zapytanie o punkt i okolicę, w tym zbiory rastrowe, podsumowanie dla gminy); pozostaje własny asystent w oknie wyboru (LLM nad katalogiem).
4. **Kolejne wizualizacje i źródła:** ikony/symbole, wyciąganie powierzchni w 3D, oś czasu, przepływy, kafle wektorowe (MVT/PMTiles), OGC API Features i WFS jako typ źródła.
5. **Własna warstwa danych:** trwałe przechowywanie danych (Cloudflare D1/R2, ewentualnie PostGIS), zapytania przestrzenne przez wiele źródeł, wstępnie obliczone agregacje dla dużych danych.
6. **Oceny autorskie:** warstwy z ocenami blogerów i recenzentów hostowane przez portal, typ wizualizacji `rating` (zob. [propozycję](https://mapadanych.pl/dokumentacja/o-projekcie.md#autorska-hodnoceni-dalsi-verze)).

---

# Przykłady

## manifest-minimal.json

Najmniejszy sensowny manifest: statyczny plik GeoJSON, tryb full.

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

## manifest-complete.json

Manifest ze wszystkimi głównymi możliwościami: bbox, filtry, kolory według wartości, grupowanie, kartogram, WMS.

```json
{
  "$schema": "https://mapadanych.pl/schema/0.1/manifest.json",
  "protocol": "0.1",
  "provider": {
    "id": "mesto-priklad",
    "name": "Město Příklad",
    "description": "Otevřená data statutárního města Příklad.",
    "homepage": "https://www.mesto-priklad.cz/",
    "contact": {
      "email": "opendata@mesto-priklad.cz"
    }
  },
  "license": {
    "name": "CC BY 4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/",
    "attribution": "© Město Příklad"
  },
  "datasets": [
    {
      "id": "kontejnery",
      "title": "Kontejnery na tříděný odpad",
      "description": "Stanoviště kontejnerů na papír, plast a sklo včetně data posledního vývozu.",
      "category": "infrastructure",
      "tags": [
        "odpady"
      ],
      "keywords": [
        "odpad",
        "kontejner",
        "třídění",
        "tříděný odpad",
        "popelnice",
        "papír",
        "plast",
        "sklo",
        "recyklace"
      ],
      "useCases": [
        "housing",
        "public-administration"
      ],
      "coverage": {
        "bbox": [
          16.43,
          49.1,
          16.73,
          49.3
        ],
        "area": "Město Příklad",
        "minZoom": 11
      },
      "temporal": {
        "updated": "2026-10-06",
        "frequency": "denně"
      },
      "source": {
        "type": "geojson",
        "url": "https://data.mesto-priklad.cz/datovamapa/kontejnery",
        "mode": "bbox",
        "maxFeatures": 5000
      },
      "presentation": {
        "type": "circle",
        "color": {
          "field": "druh",
          "type": "categorical",
          "values": {
            "papír": "#2563eb",
            "plast": "#eab308",
            "sklo": "#16a34a"
          },
          "default": "#64748b"
        },
        "radius": {
          "field": "objem",
          "type": "interpolate",
          "stops": [
            [
              500,
              4
            ],
            [
              3000,
              9
            ]
          ]
        },
        "strokeColor": "#ffffff",
        "strokeWidth": 1.5,
        "cluster": {
          "radius": 40,
          "maxZoom": 15
        },
        "legend": [
          {
            "label": "Papír",
            "color": "#2563eb"
          },
          {
            "label": "Plast",
            "color": "#eab308"
          },
          {
            "label": "Sklo",
            "color": "#16a34a"
          }
        ]
      },
      "fields": [
        {
          "key": "druh",
          "label": "Druh odpadu",
          "type": "string",
          "primary": true
        },
        {
          "key": "objem",
          "label": "Objem",
          "type": "integer",
          "unit": "l"
        },
        {
          "key": "vyvoz",
          "label": "Poslední vývoz",
          "type": "date"
        }
      ],
      "params": [
        {
          "key": "druh",
          "label": "Druh odpadu",
          "type": "multi-enum",
          "options": [
            {
              "value": "papír",
              "label": "Papír"
            },
            {
              "value": "plast",
              "label": "Plast"
            },
            {
              "value": "sklo",
              "label": "Sklo"
            }
          ]
        }
      ],
      "cache": {
        "ttl": 3600,
        "store": true
      }
    },
    {
      "id": "hluk",
      "title": "Hluková mapa",
      "description": "Strategická hluková mapa – denní hladina hluku ze silniční dopravy.",
      "category": "risks",
      "keywords": [
        "hluk",
        "hlučnost",
        "doprava",
        "decibely",
        "Ldvn"
      ],
      "useCases": [
        "housing",
        "construction",
        "land-purchase"
      ],
      "coverage": {
        "bbox": [
          16.43,
          49.1,
          16.73,
          49.3
        ],
        "area": "Město Příklad",
        "minZoom": 10
      },
      "source": {
        "type": "geojson",
        "url": "https://data.mesto-priklad.cz/datovamapa/hluk",
        "mode": "bbox"
      },
      "presentation": {
        "type": "fill",
        "color": {
          "field": "db",
          "type": "step",
          "default": "#fef9c3",
          "stops": [
            [
              55,
              "#fde047"
            ],
            [
              60,
              "#fb923c"
            ],
            [
              65,
              "#ef4444"
            ],
            [
              70,
              "#7f1d1d"
            ]
          ]
        },
        "opacity": 0.55,
        "outlineWidth": 0
      },
      "fields": [
        {
          "key": "db",
          "label": "Hladina hluku",
          "type": "number",
          "unit": "dB",
          "decimals": 0
        }
      ],
      "cache": {
        "ttl": 86400
      }
    },
    {
      "id": "uzemni-plan",
      "title": "Územní plán",
      "description": "Hlavní výkres územního plánu jako rastrová vrstva z WMS.",
      "category": "territory",
      "keywords": [
        "územní plán",
        "ÚP",
        "funkční využití",
        "zastavitelné plochy"
      ],
      "useCases": [
        "construction",
        "land-purchase",
        "investment"
      ],
      "coverage": {
        "bbox": [
          16.43,
          49.1,
          16.73,
          49.3
        ],
        "area": "Město Příklad"
      },
      "source": {
        "type": "raster",
        "tiles": [
          "https://gis.mesto-priklad.cz/wms?service=WMS&version=1.1.1&request=GetMap&layers=up_hlavni&styles=&format=image/png&transparent=true&srs=EPSG:3857&width=256&height=256&bbox={bbox-epsg-3857}"
        ]
      },
      "presentation": {
        "type": "raster",
        "opacity": 0.7
      }
    }
  ]
}
```

## data-points.json

Odpowiedź z punktami wraz z rozszerzeniem dm.

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1842,
      "geometry": {
        "type": "Point",
        "coordinates": [
          16.6081,
          49.1951
        ]
      },
      "properties": {
        "druh": "papír",
        "objem": 1100,
        "vyvoz": "2026-10-01"
      },
      "dm": {
        "title": "Kontejner Náměstí Svobody",
        "url": "https://www.mesto-priklad.cz/odpady/1842"
      }
    },
    {
      "type": "Feature",
      "id": 1843,
      "geometry": {
        "type": "Point",
        "coordinates": [
          16.6102,
          49.1938
        ]
      },
      "properties": {
        "druh": "sklo",
        "objem": 1500,
        "vyvoz": "2026-09-28"
      }
    }
  ],
  "dm": {
    "generated": "2026-10-06T08:00:00Z",
    "ttl": 3600,
    "total": 2,
    "truncated": false
  }
}
```

## detail-jizda.json

Szczegóły obiektu na żądanie: przejazd pociągu z osią czasu przystanków i trasą do wyróżnienia na mapie.

```json
{
  "title": "RJ 1000",
  "subtitle": "→ Praha-Zahradní Město · RegioJet a.s.",
  "badge": {
    "text": "RJ 1000",
    "color": "#0f766e",
    "textColor": "#ffffff"
  },
  "status": {
    "label": "+8 min",
    "tone": "warning"
  },
  "fields": [
    {
      "label": "Linka",
      "value": "S2"
    }
  ],
  "tags": [
    "Bezbariérový vlak",
    "Přeprava kol"
  ],
  "notes": [
    "Příklad: čas v odhadu je plán posunutý o poslední známé zpoždění."
  ],
  "journey": {
    "calls": [
      {
        "name": "Ostrava hlavní nádraží",
        "departure": "2026-11-04T05:05:00+01:00",
        "scheduledDeparture": "2026-11-04T05:05:00+01:00",
        "platform": "2",
        "state": "passed"
      },
      {
        "name": "Pardubice hlavní nádraží",
        "arrival": "2026-11-04T07:30:00+01:00",
        "departure": "2026-11-04T07:38:00+01:00",
        "scheduledArrival": "2026-11-04T07:22:00+01:00",
        "scheduledDeparture": "2026-11-04T07:30:00+01:00",
        "platform": "3",
        "state": "current"
      },
      {
        "name": "Praha hlavní nádraží",
        "arrival": "2026-11-04T08:48:00+01:00",
        "departure": "2026-11-04T08:55:00+01:00",
        "scheduledArrival": "2026-11-04T08:40:00+01:00",
        "scheduledDeparture": "2026-11-04T08:47:00+01:00",
        "estimated": true,
        "platform": "5",
        "state": "upcoming"
      },
      {
        "name": "Praha-Zahradní Město",
        "arrival": "2026-11-04T09:05:00+01:00",
        "scheduledArrival": "2026-11-04T08:57:00+01:00",
        "estimated": true,
        "state": "upcoming"
      }
    ]
  },
  "highlight": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "LineString",
          "coordinates": [
            [
              18.27,
              49.85
            ],
            [
              15.77,
              50.03
            ]
          ]
        },
        "properties": {
          "role": "passed"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "LineString",
          "coordinates": [
            [
              15.77,
              50.03
            ],
            [
              14.43,
              50.08
            ],
            [
              14.6,
              50.07
            ]
          ]
        },
        "properties": {
          "role": "upcoming"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            15.77,
            50.03
          ]
        },
        "properties": {
          "role": "current",
          "name": "Pardubice hlavní nádraží"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            14.43,
            50.08
          ]
        },
        "properties": {
          "role": "stop",
          "name": "Praha hlavní nádraží"
        }
      }
    ]
  },
  "color": "#0f766e",
  "generated": "2026-11-04T07:35:00Z",
  "ttl": 30
}
```

## data-doprava.json

Odpowiedź zbioru z profilem transit_vehicles: pojazdy transportu publicznego z dm.transit.

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "1234|20261104",
      "geometry": {
        "type": "Point",
        "coordinates": [
          14.4352,
          50.0833
        ]
      },
      "properties": {
        "vlak": "R 1234",
        "cil": "Brno hl.n.",
        "dopravce": "České dráhy",
        "zpozdeni_min": 6,
        "aktualizace": "2026-11-04T07:35:10Z"
      },
      "dm": {
        "transit": {
          "mode": "rail",
          "label": "R 1234",
          "headsign": "Brno hl.n.",
          "operator": "České dráhy",
          "delay_min": 6,
          "delay_band": "minor",
          "bearing": 135,
          "trip_ref": "1234|20261104",
          "observed_at": "2026-11-04T07:35:10Z"
        }
      }
    },
    {
      "type": "Feature",
      "id": "bus:4521",
      "geometry": {
        "type": "Point",
        "coordinates": [
          18.2625,
          49.8347
        ]
      },
      "properties": {
        "linka": "37",
        "cil": "Ostrava, Hlavní nádraží",
        "aktualizace": "2026-11-04T07:35:02Z"
      },
      "dm": {
        "transit": {
          "mode": "bus",
          "label": "37",
          "headsign": "Ostrava, Hlavní nádraží",
          "delay_band": "unknown",
          "observed_at": "2026-11-04T07:35:02Z"
        }
      }
    }
  ],
  "dm": {
    "generated": "2026-11-04T07:35:20Z",
    "ttl": 30
  }
}
```

## data-polygons.json

Odpowiedź z obszarem (polygon) i wartością liczbową do kartogramu.

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "h-001",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              16.6,
              49.19
            ],
            [
              16.61,
              49.19
            ],
            [
              16.61,
              49.2
            ],
            [
              16.6,
              49.2
            ],
            [
              16.6,
              49.19
            ]
          ]
        ]
      },
      "properties": {
        "db": 62
      }
    }
  ],
  "dm": {
    "ttl": 86400
  }
}
```

---

# Źródła danych portalu MapaDanych

Katalog wszystkich podłączonych dostawców i zbiorów danych (protokół 0.1, wygenerowano 2026-11-07T06:27:35.947Z). Maszynowo: https://mapadanych.pl/api/catalog. Dane zbiorów GeoJSON: `GET https://mapadanych.pl/api/data/{provider}/{dataset}` (zob. https://mapadanych.pl/dokumentacja/api.md).

## Główny Urząd Geodezji i Kartografii

- Id: `gugik`
- Opis: Państwowe dane mapowe Polski z geoportal.gov.pl: ortofotomapa, granice administracyjne, działki ewidencyjne, punkty adresowe, plany miejscowe, sieci uzbrojenia terenu i mapa topograficzna.
- Strona: https://www.geoportal.gov.pl/
- Licencja: CC BY 4.0 (https://dane.gov.pl/pl/dataset/2026), atrybucja „© GUGiK. Opracowano na podstawie materiałów państwowego zasobu geodezyjnego i kartograficznego”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Ortofotomapa

- Klucz: `gugik/ortofotomapa`
- Opis: Barwne zdjęcie lotnicze całej Polski z geoportal.gov.pl – domy, działki, pola i lasy. Rozdzielczość do kilku centymetrów w miastach.
- Kategoria: Teren i kataster
- Słowa kluczowe: zdjęcie lotnicze, ortofotomapa, ortofoto, satelita, zdjęcie, geoportal
- Zastosowania: construction, land-purchase, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: co roku dla części kraju
- Atrybucja: © GUGiK. Opracowano na podstawie materiałów państwowego zasobu geodezyjnego i kartograficznego (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/gugik/ortofotomapa

### Działki ewidencyjne

- Klucz: `gugik/dzialki-ewidencyjne`
- Opis: Granice i numery działek z ewidencji gruntów i budynków, zebrane z powiatów w Krajowej Integracji Ewidencji Gruntów. Granice widać po dużym przybliżeniu, numery jeszcze bliżej.
- Kategoria: Teren i kataster
- Słowa kluczowe: działka, działka ewidencyjna, ewidencja gruntów, numer działki, kataster, granice działki, EGiB
- Zastosowania: construction, land-purchase, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 17
- Aktualność: codziennie
- Atrybucja: © GUGiK. Opracowano na podstawie materiałów państwowego zasobu geodezyjnego i kartograficznego (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/gugik/dzialki-ewidencyjne

### Granice administracyjne

- Klucz: `gugik/granice-administracyjne`
- Opis: Granice państwa, województw, powiatów i gmin z Państwowego Rejestru Granic.
- Kategoria: Teren i kataster
- Słowa kluczowe: granice, gmina, powiat, województwo, PRG, podział administracyjny
- Zastosowania: public-administration, land-purchase
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Atrybucja: © GUGiK. Opracowano na podstawie materiałów państwowego zasobu geodezyjnego i kartograficznego (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/gugik/granice-administracyjne

### Punkty adresowe i ulice

- Klucz: `gugik/punkty-adresowe`
- Opis: Ulice i numery adresowe z Krajowej Integracji Numeracji Adresowej. Ulice widać po przybliżeniu, numery domów jeszcze bliżej.
- Kategoria: Teren i kataster
- Słowa kluczowe: adres, numer domu, ulica, punkt adresowy, numeracja adresowa, PRG
- Zastosowania: housing, public-administration
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 15
- Atrybucja: © GUGiK. Opracowano na podstawie materiałów państwowego zasobu geodezyjnego i kartograficznego (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/gugik/punkty-adresowe

### Miejscowe plany zagospodarowania przestrzennego

- Klucz: `gugik/plany-miejscowe`
- Opis: Miejscowe plany z gmin włączonych do Krajowej Integracji MPZP: granice planów, a po przybliżeniu strefy przeznaczenia terenu z symbolami (np. MN zabudowa mieszkaniowa jednorodzinna) i linie zabudowy. Gminy bez usługi WMS na mapie nie ma; obowiązuje tekst uchwały w gminie.
- Kategoria: Teren i kataster
- Słowa kluczowe: plan miejscowy, MPZP, plan zagospodarowania przestrzennego, przeznaczenie terenu, linia zabudowy, warunki zabudowy, działka budowlana
- Zastosowania: construction, land-purchase, housing, investment
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 14
- Aktualność: na bieżąco, według gmin
- Atrybucja: © GUGiK, Krajowa Integracja MPZP; dane gmin (Warunki dostawcy)
- Mapa: https://mapadanych.pl/mapa/gugik/plany-miejscowe

### Sieci uzbrojenia terenu

- Klucz: `gugik/uzbrojenie-terenu`
- Opis: Przewody wodociągowe, kanalizacyjne, gazowe, elektroenergetyczne, ciepłownicze i telekomunikacyjne z powiatowych baz GESUT, zebrane w Krajowej Integracji Uzbrojenia Terenu. Widać je dopiero przy dużym przybliżeniu i tylko w powiatach włączonych do usługi.
- Kategoria: Teren i kataster
- Słowa kluczowe: uzbrojenie terenu, GESUT, sieć wodociągowa, kanalizacja, gazociąg, linia energetyczna, media, przyłącze
- Zastosowania: construction, land-purchase, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 17
- Aktualność: na bieżąco, według powiatów
- Atrybucja: © GUGiK, Krajowa Integracja Uzbrojenia Terenu; dane powiatów (Warunki dostawcy)
- Mapa: https://mapadanych.pl/mapa/gugik/uzbrojenie-terenu

### Mapa topograficzna

- Klucz: `gugik/mapa-topograficzna`
- Opis: Urzędowa mapa topograficzna Polski z geoportal.gov.pl: zabudowa, drogi, lasy, wody i poziomice. Zasłania mapę podkładową.
- Kategoria: Teren i kataster
- Słowa kluczowe: mapa topograficzna, poziomice, rzeźba terenu, mapa urzędowa, geoportal
- Zastosowania: tourism, construction
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Atrybucja: © GUGiK. Opracowano na podstawie materiałów państwowego zasobu geodezyjnego i kartograficznego (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/gugik/mapa-topograficzna

## Generalna Dyrekcja Ochrony Środowiska

- Id: `gdos`
- Opis: Formy ochrony przyrody z Centralnego Rejestru Form Ochrony Przyrody: parki narodowe i krajobrazowe, rezerwaty, Natura 2000, pomniki przyrody.
- Strona: https://www.gov.pl/web/gdos
- Licencja: CC0 1.0 (https://dane.gov.pl/pl/dataset/485), atrybucja „Generalna Dyrekcja Ochrony Środowiska”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Parki narodowe, rezerwaty i parki krajobrazowe

- Klucz: `gdos/obszary-chronione`
- Opis: Obszarowe formy ochrony przyrody: parki narodowe, rezerwaty przyrody, parki krajobrazowe i obszary chronionego krajobrazu. W każdej obowiązują inne ograniczenia zabudowy i użytkowania.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: park narodowy, rezerwat przyrody, park krajobrazowy, obszar chronionego krajobrazu, ochrona przyrody, CRFOP
- Zastosowania: construction, land-purchase, tourism
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: na bieżąco
- Atrybucja: Generalna Dyrekcja Ochrony Środowiska (CC0 1.0)
- Mapa: https://mapadanych.pl/mapa/gdos/obszary-chronione

### Natura 2000

- Klucz: `gdos/natura-2000`
- Opis: Obszary specjalnej ochrony ptaków i specjalne obszary ochrony siedlisk sieci Natura 2000 w Polsce. Inwestycję na takim obszarze ocenia się pod kątem wpływu na przyrodę.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: natura 2000, obszar specjalnej ochrony ptaków, specjalny obszar ochrony siedlisk, OSO, SOO, ochrona przyrody
- Zastosowania: construction, land-purchase
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: na bieżąco
- Atrybucja: Generalna Dyrekcja Ochrony Środowiska (CC0 1.0)
- Mapa: https://mapadanych.pl/mapa/gdos/natura-2000

### Pomniki przyrody i użytki ekologiczne

- Klucz: `gdos/pomniki-przyrody`
- Opis: Pomniki przyrody (drzewa, głazy, źródła), użytki ekologiczne, stanowiska dokumentacyjne i zespoły przyrodniczo-krajobrazowe. Widać je po przybliżeniu.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: pomnik przyrody, drzewo, użytek ekologiczny, zespół przyrodniczo-krajobrazowy, ochrona przyrody
- Zastosowania: construction, tourism
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 13
- Atrybucja: Generalna Dyrekcja Ochrony Środowiska (CC0 1.0)
- Mapa: https://mapadanych.pl/mapa/gdos/pomniki-przyrody

## Państwowy Instytut Geologiczny – PIB

- Id: `pig-pib`
- Opis: Państwowa służba geologiczna: osuwiska, mapy geologiczne, podtopienia i główne zbiorniki wód podziemnych.
- Strona: https://www.pgi.gov.pl/
- Licencja: CC BY 4.0 (https://dane.gov.pl/pl/dataset/1297), atrybucja „© PIG-PIB”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Osuwiska i tereny zagrożone

- Klucz: `pig-pib/osuwiska`
- Opis: Osuwiska i tereny zagrożone ruchami masowymi z Systemu Osłony Przeciwosuwiskowej (SOPO). Najwięcej ich jest w Karpatach. Usługa rysuje je tylko przy średnim przybliżeniu.
- Kategoria: Zagrożenia i ograniczenia
- Słowa kluczowe: osuwisko, ruchy masowe, SOPO, zagrożenie geologiczne, stok, Karpaty
- Zastosowania: construction, land-purchase, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 12
- Atrybucja: © PIG-PIB (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/pig-pib/osuwiska

### Obszary zagrożone podtopieniami

- Klucz: `pig-pib/podtopienia`
- Opis: Tereny, gdzie wody podziemne mogą podnieść się do powierzchni i zalać piwnice i fundamenty – niezależnie od wylewów rzek.
- Kategoria: Woda
- Słowa kluczowe: podtopienie, wody podziemne, zalanie piwnicy, wysoki poziom wód gruntowych, fundamenty
- Zastosowania: construction, land-purchase, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 12
- Atrybucja: © PIG-PIB (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/pig-pib/podtopienia

### Mapa geologiczna Polski 1 : 500 000

- Klucz: `pig-pib/mapa-geologiczna`
- Opis: Utwory geologiczne pod powierzchnią według przeglądowej mapy geologicznej Polski. Usługa rysuje ją tylko przy oddaleniu (do przybliżenia 10).
- Kategoria: Teren i kataster
- Słowa kluczowe: geologia, mapa geologiczna, skały, podłoże, utwory geologiczne
- Zastosowania: construction, investment
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Atrybucja: © PIG-PIB (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/pig-pib/mapa-geologiczna

### Główne zbiorniki wód podziemnych

- Klucz: `pig-pib/zbiorniki-wod-podziemnych`
- Opis: Główne Zbiorniki Wód Podziemnych (GZWP) – zasoby wody pitnej, w których obszarach obowiązują ograniczenia dla inwestycji mogących je zanieczyścić.
- Kategoria: Woda
- Słowa kluczowe: GZWP, wody podziemne, woda pitna, zbiornik wód podziemnych, hydrogeologia
- Zastosowania: construction, agriculture, investment
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Atrybucja: © PIG-PIB (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/pig-pib/zbiorniki-wod-podziemnych

## Państwowe Gospodarstwo Wodne Wody Polskie

- Id: `wody-polskie`
- Opis: Zarządca wód w Polsce. Mapy zagrożenia powodziowego z Informatycznego Systemu Osłony Kraju (ISOK).
- Strona: https://www.gov.pl/web/wody-polskie
- Licencja: CC BY 4.0 (https://dane.gov.pl/pl/dataset/2178), atrybucja „© Państwowe Gospodarstwo Wodne Wody Polskie”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Zagrożenie powodziowe – woda stuletnia (1 %)

- Klucz: `wody-polskie/powodz-q1`
- Opis: Zasięg i głębokość wody przy powodzi o prawdopodobieństwie 1 % (raz na 100 lat) według map zagrożenia powodziowego Wód Polskich. Usługa rysuje mapę dopiero po dużym przybliżeniu. Na obszarach szczególnego zagrożenia powodzią obowiązują ograniczenia zabudowy.
- Kategoria: Woda
- Słowa kluczowe: powódź, mapa zagrożenia powodziowego, zalew, ISOK, Wody Polskie, woda stuletnia, Q1%, obszar szczególnego zagrożenia powodzią
- Zastosowania: construction, land-purchase, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 14
- Atrybucja: © Państwowe Gospodarstwo Wodne Wody Polskie (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/wody-polskie/powodz-q1

### Zagrożenie powodziowe – woda dziesięcioletnia (10 %)

- Klucz: `wody-polskie/powodz-q10`
- Opis: Zasięg i głębokość wody przy powodzi o prawdopodobieństwie 10 % (raz na 10 lat) według map zagrożenia powodziowego Wód Polskich. Usługa rysuje mapę dopiero po dużym przybliżeniu. Na obszarach szczególnego zagrożenia powodzią obowiązują ograniczenia zabudowy.
- Kategoria: Woda
- Słowa kluczowe: powódź, mapa zagrożenia powodziowego, zalew, ISOK, Wody Polskie, woda dziesięcioletnia, Q10%
- Zastosowania: construction, land-purchase, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 14
- Atrybucja: © Państwowe Gospodarstwo Wodne Wody Polskie (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/wody-polskie/powodz-q10

### Zagrożenie powodziowe – woda pięćsetletnia (0,2 %)

- Klucz: `wody-polskie/powodz-q02`
- Opis: Zasięg i głębokość wody przy powodzi o prawdopodobieństwie 0,2 % (raz na 500 lat) według map zagrożenia powodziowego Wód Polskich. Usługa rysuje mapę dopiero po dużym przybliżeniu. Na obszarach szczególnego zagrożenia powodzią obowiązują ograniczenia zabudowy.
- Kategoria: Woda
- Słowa kluczowe: powódź, mapa zagrożenia powodziowego, zalew, ISOK, Wody Polskie, woda pięćsetletnia, Q0,2%
- Zastosowania: construction, land-purchase, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 14
- Atrybucja: © Państwowe Gospodarstwo Wodne Wody Polskie (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/wody-polskie/powodz-q02

## Bank Danych o Lasach

- Id: `lasy-panstwowe`
- Opis: Dane o lasach wszystkich form własności prowadzone przez Biuro Urządzania Lasu i Geodezji Leśnej na zlecenie Ministerstwa Klimatu i Środowiska.
- Strona: https://www.bdl.lasy.gov.pl/
- Licencja: CC BY 4.0 (https://dane.gov.pl/pl/dataset/629), atrybucja „Bank Danych o Lasach, bdl.lasy.gov.pl”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Zakazy wstępu do lasu

- Klucz: `lasy-panstwowe/zakazy-wstepu-do-lasu`
- Opis: Lasy, do których obowiązuje okresowy zakaz wstępu – z powodu zagrożenia pożarowego, wyrębu lub szkód. Przed wycieczką sprawdź też informację nadleśnictwa.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: zakaz wstępu do lasu, las, nadleśnictwo, wycieczka, zagrożenie pożarowe
- Zastosowania: tourism
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: codziennie
- Atrybucja: Bank Danych o Lasach, bdl.lasy.gov.pl (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/lasy-panstwowe/zakazy-wstepu-do-lasu

### Zagrożenie pożarowe lasów

- Klucz: `lasy-panstwowe/zagrozenie-pozarowe`
- Opis: Bieżący stopień zagrożenia pożarowego lasów w strefach prognostycznych, ogłaszany w sezonie od marca do września.
- Kategoria: Zagrożenia i ograniczenia
- Słowa kluczowe: zagrożenie pożarowe, pożar lasu, susza, las, stopień zagrożenia
- Zastosowania: tourism, agriculture
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: codziennie w sezonie
- Atrybucja: Bank Danych o Lasach, bdl.lasy.gov.pl (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/lasy-panstwowe/zagrozenie-pozarowe

### Drzewostany

- Klucz: `lasy-panstwowe/drzewostany`
- Opis: Wydzielenia leśne z gatunkiem panującym i wiekiem drzewostanu według Banku Danych o Lasach. Widać je po przybliżeniu.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: las, drzewostan, gatunek drzew, wiek lasu, leśnictwo, wydzielenie
- Zastosowania: agriculture, land-purchase
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 13
- Atrybucja: Bank Danych o Lasach, bdl.lasy.gov.pl (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/lasy-panstwowe/drzewostany

## Instytut Meteorologii i Gospodarki Wodnej – PIB

- Id: `imgw`
- Opis: Państwowa służba hydrologiczna i meteorologiczna. Bieżące stany wód na rzekach, pomiary automatycznych stacji meteorologicznych i ostrzeżenia meteorologiczne dla powiatów.
- Strona: https://www.imgw.pl/
- Licencja: Warunki dostawcy (https://danepubliczne.imgw.pl/apiinfo), atrybucja „Źródłem pochodzenia danych jest Instytut Meteorologii i Gospodarki Wodnej – Państwowy Instytut Badawczy. Dane IMGW-PIB zostały przetworzone.”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Stany wód na rzekach (na żywo)

- Klucz: `imgw/stany-wod`
- Opis: Bieżący stan wody na ponad 900 wodowskazach IMGW-PIB i porównanie ze stanem ostrzegawczym i alarmowym. Czerwony punkt oznacza przekroczenie stanu alarmowego – zagrożenie powodziowe. Oficjalne ostrzeżenia wydaje IMGW-PIB na hydro.imgw.pl.
- Kategoria: Woda
- Słowa kluczowe: stan wody, wodowskaz, powódź, stan alarmowy, stan ostrzegawczy, rzeka, przepływ, hydrologia
- Zastosowania: housing, construction, agriculture
- Źródło: GeoJSON, tryb `full`; tylko do wyświetlania na mapie, dane udostępnia pierwotna usługa: https://danepubliczne.imgw.pl/api/data/hydro
- Wizualizacja: `circle`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: co 10 minut
- Atrybucja: Źródłem pochodzenia danych jest Instytut Meteorologii i Gospodarki Wodnej – Państwowy Instytut Badawczy. Dane IMGW-PIB zostały przetworzone. (Warunki dostawcy)
- Mapa: https://mapadanych.pl/mapa/imgw/stany-wod

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `stacja` | Wodowskaz | string |  |
| `rzeka` | Rzeka | string |  |
| `stan` | Sytuacja | string |  |
| `stan_wody` | Stan wody | integer | cm |
| `stan_ostrzegawczy` | Stan ostrzegawczy | integer | cm |
| `stan_alarmowy` | Stan alarmowy | integer | cm |
| `przeplyw` | Przepływ | number | m³/s |
| `temperatura_wody` | Temperatura wody | number | °C |
| `pomiar` | Pomiar | datetime |  |

### Pogoda ze stacji IMGW (na żywo)

- Klucz: `imgw/pogoda`
- Opis: Temperatura powietrza, wiatr, wilgotność i opad z automatycznych stacji meteorologicznych IMGW-PIB. Kolor według temperatury; stacje bez aktualnego pomiaru temperatury są szare.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: pogoda, temperatura, wiatr, opad, wilgotność, stacja meteorologiczna, meteo
- Zastosowania: agriculture, tourism
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/imgw/pogoda
- Wizualizacja: `circle`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: co 10 minut
- Atrybucja: Źródłem pochodzenia danych jest Instytut Meteorologii i Gospodarki Wodnej – Państwowy Instytut Badawczy. Dane IMGW-PIB zostały przetworzone. (CC0 1.0)
- Mapa: https://mapadanych.pl/mapa/imgw/pogoda

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `stacja` | Stacja | string |  |
| `temperatura` | Temperatura powietrza | number | °C |
| `wiatr` | Średnia prędkość wiatru | number | m/s |
| `poryw` | Maksymalna prędkość wiatru | number | m/s |
| `wilgotnosc` | Wilgotność względna | number | % |
| `opad` | Opad (10 min) | number | mm |
| `wysokosc` | Wysokość n.p.m. | integer | m |
| `pomiar` | Pomiar temperatury | datetime |  |

### Ostrzeżenia meteorologiczne IMGW (na żywo)

- Klucz: `imgw/ostrzezenia`
- Opis: Aktualne ostrzeżenia meteorologiczne IMGW-PIB dla powiatów: burze, silny wiatr, intensywne opady, upał, mróz, oblodzenie, gęsta mgła. Kolor według najwyższego stopnia ostrzeżenia w powiecie. Oficjalny komunikat jest na meteo.imgw.pl.
- Kategoria: Zagrożenia i ograniczenia
- Słowa kluczowe: ostrzeżenie, ostrzeżenia meteorologiczne, burza, wichura, silny wiatr, upał, mróz, oblodzenie, mgła, ulewa, IMGW
- Zastosowania: housing, agriculture, tourism
- Źródło: GeoJSON, tryb `full`; tylko do wyświetlania na mapie, dane udostępnia pierwotna usługa: https://danepubliczne.imgw.pl/api/data/warningsmeteo
- Wizualizacja: `fill`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: na bieżąco
- Atrybucja: Źródłem pochodzenia danych jest Instytut Meteorologii i Gospodarki Wodnej – Państwowy Instytut Badawczy. Dane IMGW-PIB zostały przetworzone. (CC BY-NC-ND 4.0)
- Mapa: https://mapadanych.pl/mapa/imgw/ostrzezenia

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `ostrzezenie` | Ostrzeżenie | string |  |
| `stopien` | Najwyższy stopień | integer |  |
| `prawdopodobienstwo` | Prawdopodobieństwo | integer | % |
| `od` | Obowiązuje od | datetime |  |
| `do` | Obowiązuje do | datetime |  |
| `opis` | Przebieg | string |  |

## Główny Inspektorat Ochrony Środowiska

- Id: `gios`
- Opis: Państwowy Monitoring Środowiska. Polski indeks jakości powietrza ze stacji pomiarowych w całym kraju.
- Strona: https://powietrze.gios.gov.pl/
- Licencja: CC BY 4.0 (https://dane.gov.pl/pl/dataset/313), atrybucja „Źródło danych: GIOŚ – EKOINFONET. Dane przetworzone przez MapaDanych.”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Indeks jakości powietrza (na żywo)

- Klucz: `gios/indeks-jakosci-powietrza`
- Opis: Polski indeks jakości powietrza ze stacji Państwowego Monitoringu Środowiska, liczony co godzinę z najgorszego mierzonego zanieczyszczenia (pył PM10 i PM2,5, NO₂, O₃, SO₂). Pomiary urzędowe, rzadsza sieć niż czujniki obywatelskie. Widać go po przybliżeniu mapy na region.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: jakość powietrza, indeks jakości powietrza, smog, PM10, PM2,5, ozon, dwutlenek azotu, GIOŚ, stacja pomiarowa
- Zastosowania: housing, tourism
- Źródło: GeoJSON, tryb `bbox` (zapytanie z bbox i zoom); dane: https://mapadanych.pl/api/data/gios/indeks-jakosci-powietrza
- Wizualizacja: `circle`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 9
- Aktualność: co godzinę
- Atrybucja: Źródło danych: GIOŚ – EKOINFONET. Dane przetworzone przez MapaDanych. (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/gios/indeks-jakosci-powietrza

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `stacja` | Stacja | string |  |
| `indeks` | Indeks jakości powietrza | string |  |
| `krytyczne` | Decyduje | string |  |
| `pm10` | PM10 | string |  |
| `pm25` | PM2,5 | string |  |
| `no2` | NO2 | string |  |
| `o3` | O3 | string |  |
| `so2` | SO2 | string |  |
| `adres` | Adres | string |  |
| `obliczono` | Obliczono | datetime |  |

## Narodowy Instytut Dziedzictwa

- Id: `nid`
- Opis: Państwowa instytucja ochrony zabytków. Pomniki historii i obiekty z Listy światowego dziedzictwa UNESCO w Polsce.
- Strona: https://zabytek.gov.pl/
- Licencja: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/), atrybucja „Narodowy Instytut Dziedzictwa, zabytek.gov.pl”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Pomniki historii

- Klucz: `nid/pomniki-historii`
- Opis: Zabytki o szczególnym znaczeniu dla kultury Polski, uznane rozporządzeniem Prezydenta RP – katedry, zamki, układy urbanistyczne, krajobrazy kulturowe. Rozległe obiekty mają kilka punktów.
- Kategoria: Społeczeństwo i usługi
- Słowa kluczowe: pomnik historii, zabytek, dziedzictwo kulturowe, co zobaczyć, turystyka, architektura, NID
- Zastosowania: tourism, construction
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/nid/pomniki-historii
- Wizualizacja: `circle`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: przy nowych wpisach
- Atrybucja: Narodowy Instytut Dziedzictwa, zabytek.gov.pl (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/nid/pomniki-historii

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `nazwa` | Nazwa | string |  |
| `rodzaj` | Rodzaj | string |  |
| `wpis` | Data uznania | date |  |
| `adres` | Adres | string |  |
| `gmina` | Gmina | string |  |
| `wojewodztwo` | Województwo | string |  |
| `polozenie` | Dokładność położenia | string |  |

### Rejestr zabytków nieruchomych

- Klucz: `nid/rejestr-zabytkow`
- Opis: Zabytki wpisane do rejestru konserwatora zabytków – budynki, zespoły, parki, cmentarze i układy urbanistyczne. Prace przy nich wymagają pozwolenia wojewódzkiego konserwatora zabytków.
- Kategoria: Społeczeństwo i usługi
- Słowa kluczowe: rejestr zabytków, zabytek, konserwator zabytków, ochrona zabytków, budynek zabytkowy, NID
- Zastosowania: construction, land-purchase, housing, tourism
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84; od przybliżenia 10
- Atrybucja: Narodowy Instytut Dziedzictwa, zabytek.gov.pl (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/nid/rejestr-zabytkow

### Światowe dziedzictwo UNESCO w Polsce

- Klucz: `nid/unesco`
- Opis: Obiekty z Listy światowego dziedzictwa UNESCO na terenie Polski – od Starego Miasta w Krakowie po Puszczę Białowieską. Wpisy obejmujące kilka miejsc mają kilka punktów.
- Kategoria: Społeczeństwo i usługi
- Słowa kluczowe: UNESCO, światowe dziedzictwo, zabytek, co zobaczyć, turystyka, NID
- Zastosowania: tourism
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/nid/unesco
- Wizualizacja: `circle`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: przy nowych wpisach
- Atrybucja: Narodowy Instytut Dziedzictwa, zabytek.gov.pl (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/nid/unesco

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `nazwa` | Nazwa | string |  |
| `wpis` | Rok wpisu | string |  |
| `numer` | Numer na liście UNESCO | string |  |
| `adres` | Adres | string |  |
| `gmina` | Gmina | string |  |
| `wojewodztwo` | Województwo | string |  |
| `polozenie` | Dokładność położenia | string |  |

## Zarząd Transportu Miejskiego w Gdańsku

- Id: `ztm-gdansk`
- Opis: Organizator komunikacji miejskiej w Gdańsku. Pozycje autobusów i tramwajów na żywo oraz przystanki.
- Strona: https://ztm.gda.pl/otwarty-ztm
- Licencja: CC BY 4.0 (https://ckan.multimediagdansk.pl/dataset/tristar), atrybucja „Źródło: Zarząd Transportu Miejskiego w Gdańsku (ztm.gda.pl/otwarty_ztm)”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Autobusy i tramwaje w Gdańsku (na żywo)

- Klucz: `ztm-gdansk/pojazdy`
- Opis: Bieżące pozycje pojazdów komunikacji miejskiej w Gdańsku z numerem linii, kierunkiem i opóźnieniem względem rozkładu. Kolor według opóźnienia.
- Kategoria: Transport
- Słowa kluczowe: komunikacja miejska, autobus, tramwaj, ZTM Gdańsk, opóźnienie, pozycja pojazdu, na żywo, Gdańsk
- Zastosowania: transport
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/ztm-gdansk/pojazdy
- Wizualizacja: `circle`
- Zasięg: Gdańsk i okolice; bbox 18.4, 54.25, 18.95, 54.45
- Aktualność: co 20 sekund
- Atrybucja: Źródło: Zarząd Transportu Miejskiego w Gdańsku (ztm.gda.pl/otwarty_ztm) (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/ztm-gdansk/pojazdy

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `linia` | Linia | string |  |
| `kierunek` | Kierunek | string |  |
| `opoznienie` | Opóźnienie | integer | min |
| `predkosc` | Prędkość | integer | km/h |
| `pojazd` | Numer taborowy | string |  |
| `aktualizacja` | Pozycja z | datetime |  |

### Przystanki komunikacji miejskiej w Gdańsku

- Klucz: `ztm-gdansk/przystanki`
- Opis: Przystanki autobusowe i tramwajowe ZTM w Gdańsku z informacją o dostępności dla wózków.
- Kategoria: Transport
- Słowa kluczowe: przystanek, komunikacja miejska, autobus, tramwaj, ZTM Gdańsk, Gdańsk, dostępność
- Zastosowania: transport, housing
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/ztm-gdansk/przystanki
- Wizualizacja: `circle`
- Zasięg: Gdańsk i okolice; bbox 18.4, 54.25, 18.95, 54.45
- Aktualność: codziennie
- Atrybucja: Źródło: Zarząd Transportu Miejskiego w Gdańsku (ztm.gda.pl/otwarty_ztm) (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/ztm-gdansk/przystanki

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `nazwa` | Przystanek | string |  |
| `slupek` | Słupek | string |  |
| `rodzaj` | Rodzaj | string |  |
| `strefa` | Strefa | string |  |
| `dla_wozkow` | Dostępny dla wózków | boolean |  |

## nextbike

- Id: `nextbike`
- Opis: Rowery miejskie w polskich miastach. Dostępność rowerów na stacjach w czasie rzeczywistym.
- Strona: https://www.nextbike.pl/
- Licencja: CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/), atrybucja „nextbike”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Rowery miejskie nextbike (na żywo)

- Klucz: `nextbike/rowery-miejskie`
- Opis: Stacje rowerów miejskich i liczba rowerów, które można teraz wypożyczyć.
- Kategoria: Transport
- Słowa kluczowe: rower miejski, bikesharing, rower, nextbike, wypożyczalnia rowerów, mobilność
- Zastosowania: transport, tourism
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/nextbike/rowery-miejskie
- Wizualizacja: `circle`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: co minutę
- Atrybucja: nextbike (CC0 1.0)
- Mapa: https://mapadanych.pl/mapa/nextbike/rowery-miejskie

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `nazwa` | Stacja | string |  |
| `miasto` | Miasto | string |  |
| `system` | System | string |  |
| `rowery` | Wolne rowery | integer |  |
| `stojaki` | Stojaki | integer |  |
| `wolne_stojaki` | Wolne stojaki | integer |  |

## Sensor.Community

- Id: `sensor-community`
- Opis: Obywatelska sieć tanich czujników pyłu. Pomiar nieoficjalny, orientacyjny.
- Strona: https://sensor.community/pl/
- Licencja: ODC DbCL 1.0 (https://opendatacommons.org/licenses/dbcl/1-0/), atrybucja „Sensor.Community”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Pył z czujników obywatelskich (na żywo)

- Klucz: `sensor-community/pyl-z-czujnikow`
- Opis: Stężenie pyłu PM2,5 i PM10 z domowych czujników z ostatnich 5 minut. Gęstsza sieć niż stacje państwowe, ale mniejsza dokładność.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: pył, PM2,5, PM10, smog, powietrze, czujnik, niska emisja, jakość powietrza
- Zastosowania: housing
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/sensor-community/pyl-z-czujnikow
- Wizualizacja: `circle`
- Zasięg: Polska; bbox 14.12, 49, 24.15, 54.84
- Aktualność: co 5 minut
- Atrybucja: Sensor.Community (ODC DbCL 1.0)
- Mapa: https://mapadanych.pl/mapa/sensor-community/pyl-z-czujnikow

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `pm25` | PM2,5 | number | µg/m³ |
| `pm10` | PM10 | number | µg/m³ |
| `pomiar` | Pomiar (UTC) | string |  |

## Euro-Śródziemnomorskie Centrum Sejsmologiczne (EMSC)

- Id: `emsc`
- Opis: Europejskie centrum zbierające zgłoszenia obserwatoriów sejsmicznych, także polskich. Wychwytuje również słabe wstrząsy, w tym górnicze na Śląsku i w Zagłębiu Miedziowym.
- Strona: https://www.emsc-csem.org/
- Licencja: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/), atrybucja „EMSC-CSEM”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Trzęsienia ziemi w Europie i okolicy

- Klucz: `emsc/trzesienia-ziemi`
- Opis: Wstrząsy z wybranego okresu w bieżącym widoku mapy, także słabe lokalne i górnicze (Górny Śląsk, Legnicko-Głogowski Okręg Miedziowy).
- Kategoria: Zagrożenia i ograniczenia
- Słowa kluczowe: trzęsienie ziemi, wstrząs, sejsmiczność, wstrząs górniczy, tąpnięcie, Śląsk, LGOM, Podhale
- Zastosowania: construction, housing
- Źródło: GeoJSON, tryb `bbox` (zapytanie z bbox i zoom); dane: https://mapadanych.pl/api/data/emsc/trzesienia-ziemi
- Wizualizacja: `circle`
- Zasięg: Świat, szczegółowo Europa; bbox -180, -85, 180, 85
- Aktualność: na bieżąco
- Atrybucja: EMSC-CSEM (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/emsc/trzesienia-ziemi

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `miejsce` | Miejsce | string |  |
| `magnituda` | Magnituda | number |  |
| `glebokosc` | Głębokość | number | km |
| `czas` | Czas | datetime |  |
| `godzin_temu` | Godzin temu | integer | h |
| `link` | Szczegóły u źródła | url |  |
| `zrodlo` | Obserwatorium | string |  |

| Parametr | Etykieta | Typ | Opcje / zakres | Domyślnie |
|---|---|---|---|---|
| `dni` | Z ostatnich | enum | `1`, `7`, `30`, `365` | 30 |
| `minmag` | Najmniejsza magnituda | number | 0–7 | 0 |

## U.S. Geological Survey

- Id: `usgs`
- Opis: Amerykańska służba geologiczna. Światowy katalog trzęsień ziemi aktualizowany co minutę.
- Strona: https://earthquake.usgs.gov/
- Licencja: Public domain (https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits), atrybucja „USGS”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Trzęsienia ziemi na świecie

- Klucz: `usgs/trzesienia-ziemi`
- Opis: Trzęsienia ziemi zarejestrowane na całym świecie. Wielkość koła odpowiada magnitudzie, kolor – wiekowi wstrząsu.
- Kategoria: Zagrożenia i ograniczenia
- Słowa kluczowe: trzęsienie ziemi, wstrząs, sejsmiczność, magnituda, tsunami
- Zastosowania: tourism, investment
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/usgs/trzesienia-ziemi
- Wizualizacja: `circle`
- Zasięg: Świat; bbox -180, -85, 180, 85
- Aktualność: co minutę
- Atrybucja: USGS (Public domain)
- Mapa: https://mapadanych.pl/mapa/usgs/trzesienia-ziemi

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `miejsce` | Miejsce | string |  |
| `magnituda` | Magnituda | number |  |
| `glebokosc` | Głębokość | number | km |
| `czas` | Czas | datetime |  |
| `godzin_temu` | Godzin temu | integer | h |
| `link` | Szczegóły u źródła | url |  |
| `tsunami` | Ostrzeżenie przed tsunami | boolean |  |

| Parametr | Etykieta | Typ | Opcje / zakres | Domyślnie |
|---|---|---|---|---|
| `okres` | Okres i siła | enum | `2.5_day`, `2.5_week`, `4.5_month`, `significant_month` | 2.5_week |

## Global Disaster Alert and Coordination System

- Id: `gdacs`
- Opis: Wspólny system ostrzegania ONZ i Komisji Europejskiej przed klęskami żywiołowymi.
- Strona: https://www.gdacs.org/
- Licencja: Warunki GDACS (https://www.gdacs.org/About/termsofuse.aspx), atrybucja „GDACS (ONZ, Komisja Europejska)”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Trwające katastrofy na świecie

- Klucz: `gdacs/katastrofy`
- Opis: Bieżące ostrzeżenia przed trzęsieniami ziemi, cyklonami, powodziami, wulkanami, suszą i pożarami. Kolor według stopnia zagrożenia, ostrzeżenia powstają automatycznie.
- Kategoria: Zagrożenia i ograniczenia
- Słowa kluczowe: katastrofa, powódź, cyklon, huragan, wulkan, susza, pożar, ostrzeżenie
- Zastosowania: tourism, investment
- Źródło: GeoJSON, tryb `full`; dane: https://mapadanych.pl/api/data/gdacs/katastrofy
- Wizualizacja: `circle`
- Zasięg: Świat; bbox -180, -85, 180, 85
- Aktualność: na bieżąco
- Atrybucja: GDACS (ONZ, Komisja Europejska) (Warunki GDACS)
- Mapa: https://mapadanych.pl/mapa/gdacs/katastrofy

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `nazwa` | Zdarzenie | string |  |
| `typ` | Typ | string |  |
| `stopien` | Stopień zagrożenia | string |  |
| `wynik` | Wynik ostrzeżenia | number |  |
| `kraj` | Kraj | string |  |
| `od` | Od | datetime |  |
| `do` | Do | datetime |  |
| `link` | Raport GDACS | url |  |

| Parametr | Etykieta | Typ | Opcje / zakres | Domyślnie |
|---|---|---|---|---|
| `typ` | Rodzaje zdarzeń | multi-enum | `EQ`, `TC`, `FL`, `VO`, `DR`, `WF` |  |

## Wikipedia

- Id: `wikipedia`
- Opis: Wolna encyklopedia. Artykuły ze współrzędnymi z polskiej Wikipedii.
- Strona: https://pl.wikipedia.org/
- Licencja: CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/), atrybucja „Wikipedia”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Artykuły Wikipedii w okolicy

- Klucz: `wikipedia/artykuly`
- Opis: Miejsca, budowle i zabytki, o których jest artykuł w polskiej Wikipedii. Szukamy w okolicy środka mapy (ok. 20 × 20 km).
- Kategoria: Społeczeństwo i usługi
- Słowa kluczowe: wikipedia, zabytek, ciekawostka, historia, co zobaczyć, turystyka, artykuł
- Zastosowania: tourism, housing
- Źródło: GeoJSON, tryb `bbox` (zapytanie z bbox i zoom); dane: https://mapadanych.pl/api/data/wikipedia/artykuly
- Wizualizacja: `circle`
- Zasięg: Świat; bbox -180, -85, 180, 85; od przybliżenia 12
- Aktualność: na bieżąco
- Atrybucja: Wikipedia (CC BY-SA 4.0)
- Mapa: https://mapadanych.pl/mapa/wikipedia/artykuly

| Właściwość | Etykieta | Typ | Jednostka |
|---|---|---|---|
| `nazwa` | Artykuł | string |  |
| `opis` | Opis | string |  |
| `typ` | Typ | string |  |
| `obraz` | Obraz | image |  |
| `link` | Wikipedia | url |  |

## NASA Earth Observing System (GIBS)

- Id: `nasa`
- Opis: Codzienne zdjęcia satelitarne Ziemi z satelitów NASA.
- Strona: https://www.earthdata.nasa.gov/engage/open-data-services-software/earthdata-developer-portal/gibs-api
- Licencja: NASA open data (https://www.earthdata.nasa.gov/engage/open-data-services-software/data-and-information-policy), atrybucja „NASA EOSDIS GIBS”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Zdjęcie satelitarne dnia

- Klucz: `nasa/zdjecie-satelitarne-dnia`
- Opis: Najnowsze dzienne zdjęcie z satelity Terra (MODIS) w barwach naturalnych. Pokazuje zachmurzenie, śnieg, dym czy zmętnienie wody po powodziach. Rozdzielczość ok. 250 m.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: satelita, zdjęcie satelitarne, zachmurzenie, pogoda, śnieg, MODIS
- Zastosowania: agriculture, tourism
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Świat; bbox -180, -85, 180, 85
- Aktualność: codziennie
- Atrybucja: NASA EOSDIS GIBS (NASA open data)
- Mapa: https://mapadanych.pl/mapa/nasa/zdjecie-satelitarne-dnia

### Światła nocą

- Klucz: `nasa/swiatla-nocne`
- Opis: Sztuczne oświetlenie Ziemi w nocy (VIIRS Black Marble). Pokazuje zabudowę, drogi i zanieczyszczenie światłem.
- Kategoria: Społeczeństwo i usługi
- Słowa kluczowe: światła nocą, zanieczyszczenie światłem, oświetlenie, zabudowa, noc
- Zastosowania: housing, investment
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Świat; bbox -180, -85, 180, 85
- Atrybucja: NASA EOSDIS GIBS (NASA open data)
- Mapa: https://mapadanych.pl/mapa/nasa/swiatla-nocne

## Europejska Agencja Środowiska

- Id: `eea`
- Strona: https://www.eea.europa.eu/
- Licencja: CC BY 4.0 (https://www.eea.europa.eu/en/legal-notice), atrybucja „© EEA”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Pył PM2,5 – średnia roczna

- Klucz: `eea/pyl-pm25`
- Opis: Średnie roczne stężenie pyłu drobnego PM2,5 w siatce 1 km dla całej Europy, modelowane z pomiarów stacji, danych satelitarnych i innych. Pokazuje, gdzie powietrze jest długotrwale gorsze – w odróżnieniu od pomiarów na żywo nie zależy od dzisiejszej pogody. Zalecenie WHO to 5 µg/m³, norma UE 25 µg/m³ (od 2030 r. 10 µg/m³).
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: pył, PM2,5, zanieczyszczenie powietrza, jakość powietrza, smog, średnia roczna, pył drobny
- Zastosowania: housing, investment
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Europa; bbox -31, 27, 45, 72
- Aktualność: 2022
- Atrybucja: © EEA (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/eea/pyl-pm25

### Natura 2000 w Europie

- Klucz: `eea/natura-2000`
- Opis: Specjalne obszary ochrony siedlisk i obszary specjalnej ochrony ptaków sieci Natura 2000 we wszystkich państwach UE.
- Kategoria: Przyroda i krajobraz
- Słowa kluczowe: natura 2000, obszar specjalnej ochrony, ochrona przyrody, SOO, OSO, ochrona ptaków
- Zastosowania: construction, land-purchase
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Unia Europejska; bbox -31, 27, 45, 72
- Aktualność: co roku
- Atrybucja: © EEA (CC BY 4.0)
- Mapa: https://mapadanych.pl/mapa/eea/natura-2000

## OpenStreetMap – mapy społecznościowe

- Id: `osm`
- Opis: Mapy tematyczne z danych OpenStreetMap od projektów wolontariuszy (Waymarked Trails, OpenRailwayMap, OpenTopoMap). Serwery mają ograniczoną przepustowość.
- Strona: https://www.openstreetmap.org/
- Licencja: ODbL / CC BY-SA (https://www.openstreetmap.org/copyright), atrybucja „dane © współtwórcy OpenStreetMap”
- Manifestem zarządza MapaDanych (usługa publiczna, właściciel danych jeszcze sam się nie podłączył).

### Szlaki turystyczne

- Klucz: `osm/szlaki-turystyczne`
- Opis: Znakowane szlaki piesze wraz z kolorem znakowania (PTTK) z OpenStreetMap.
- Kategoria: Transport
- Słowa kluczowe: turystyka, szlak turystyczny, PTTK, szlak pieszy, wycieczka, góry
- Zastosowania: tourism
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Świat; bbox -180, -85, 180, 85
- Aktualność: codziennie
- Atrybucja: Waymarked Trails, dane © współtwórcy OpenStreetMap (CC BY-SA 3.0)
- Mapa: https://mapadanych.pl/mapa/osm/szlaki-turystyczne

### Trasy rowerowe

- Klucz: `osm/trasy-rowerowe`
- Opis: Znakowane trasy rowerowe i drogi dla rowerów z OpenStreetMap (Waymarked Trails): międzynarodowe (EuroVelo, Green Velo), krajowe i lokalne.
- Kategoria: Transport
- Słowa kluczowe: trasa rowerowa, rower, kolarstwo, droga dla rowerów, Green Velo, EuroVelo, wycieczka
- Zastosowania: tourism, transport
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Świat; bbox -180, -85, 180, 85
- Aktualność: codziennie
- Atrybucja: Waymarked Trails, dane © współtwórcy OpenStreetMap (CC BY-SA 3.0)
- Mapa: https://mapadanych.pl/mapa/osm/trasy-rowerowe

### Sieć kolejowa

- Klucz: `osm/koleje`
- Opis: Linie kolejowe, stacje i bocznice całego świata z OpenRailwayMap (dane OpenStreetMap).
- Kategoria: Transport
- Słowa kluczowe: kolej, pociąg, linia kolejowa, stacja, bocznica
- Zastosowania: transport, housing
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Świat; bbox -180, -85, 180, 85
- Atrybucja: OpenRailwayMap, dane © współtwórcy OpenStreetMap (CC BY-SA 2.0)
- Mapa: https://mapadanych.pl/mapa/osm/koleje

### Mapa topograficzna

- Klucz: `osm/mapa-topograficzna`
- Opis: Krajobraz z poziomicami i cieniowaniem terenu (OpenTopoMap). Zasłania mapę podkładową.
- Kategoria: Teren i kataster
- Słowa kluczowe: mapa topograficzna, poziomice, teren, mapa turystyczna, rzeźba terenu
- Zastosowania: tourism, construction
- Źródło: kafelki rastrowe (wczytywane bezpośrednio ze źródła)
- Wizualizacja: `raster`
- Zasięg: Świat; bbox -180, -85, 180, 85
- Atrybucja: © OpenTopoMap, dane © współtwórcy OpenStreetMap (CC BY-SA 3.0)
- Mapa: https://mapadanych.pl/mapa/osm/mapa-topograficzna