API portalu MapaDanych

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.

Przegląd

Katalog

GET /api/catalog

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

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.

Dane

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

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:

{ "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ół) 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

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.

Wyszukiwanie miejsca

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

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

GET /api/nearby

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.

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

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

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

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

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.

{
  "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": [] }
}

Serwer MCP

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

Połączenie:

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

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

Link do mapy

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

Kody ustaleń

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

Manifest

Dane

Test na żywo i proxy