MapaDanych – wizja

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

Czym jest MapaDanych

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:

Dostawca danych publikuje manifest (opis siebie i swoich zbiorów danych) oraz endpoint danych zgodny z protokołem MapaDanych.
Dostawca rejestruje manifest; po zatwierdzeniu przez operatora zbiory pojawiają się w katalogu.
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.

Korzyści

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

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.

Zasady

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

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ść)

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

zrozumie miejsce (geokodowanie gminy / adresu / działki) i przesunie mapę,
zrozumie cel (budowa) i wybierze odpowiednie zbiory według useCases, keywords i opisów w manifestach,
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

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)

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.

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

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.
Rejestracja dostawców: samoobsługowa rejestracja z zatwierdzaniem jest gotowa (formularz, API, MCP); pozostaje monitorowanie dostępności źródeł.
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).
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.
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.
Oceny autorskie: warstwy z ocenami blogerów i recenzentów hostowane przez portal, typ wizualizacji rating (zob. propozycję).