Protokół MapaDanych 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 i JSON Schema danych – generowane ze schematów zod w src/lib/protocol/,
• kontrakt OpenAPI dostawcy.

Przygotowanie danych krok po kroku (zwłaszcza dla agentów AI) opisuje poradnik dla agentów AI, przystępne wprowadzenie znajdziesz w przewodniku dla dostawców. Poprawne wzorce: manifest-complete.json, data-points.json.

Przegląd

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

• 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

Zbiór danych

source

geojson – format natywny.

{ "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.

{ "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

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:

{ "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.

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

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

params

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

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

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.

{
  "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). 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. Bez żadnego z nich zostanie tylko suwak okresu.

Zmiany w czasie i 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). 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.

{
  "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

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

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

Opcjonalne rozszerzenia:

{
  "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.
• 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).
• 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.

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

{
  "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:

{
  "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

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

"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.

{
  "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.

Transport

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

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.

{
  "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.

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

Zgodność z protokołem sprawdza walidator (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), ścieżkę path, a przy zaleceniach wskazówkę hint. Kody nie zmieniają się między wersjami minor, nowe mogą dochodzić.

Rozwój protokołu

• 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ń.