MapaDanych.pl

Strojově čitelná verze: /cs/dokumentacja/dla-dostawcow.md

Podłącz swoje dane do portalu MapaDanych

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. Zawiera procedurę krok po kroku, szablony kodu i kryteria ukończenia pracy. Cała dokumentacja jest czytelna maszynowo: llms.txt, serwer MCP, walidator.

Trzy sposoby podłączenia

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

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

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

2. Dane

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.

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

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:

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ół.

3. Wizualizacja

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

4. Weryfikacja

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

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

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

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:

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

Odnośniki