GUGiK Logo

Główny Urząd Geodezji i Kartografii

Specyfikacja usługi ULDK

Logo Prawe

Usługa ULDK umożliwia wyszukiwanie obiektów oraz współrzędnych na podstawie identyfikatora szukanego obiektu lub poprzez wskazanie współrzędnych XY punktu, który znajduje się wewnątrz obiektu.

Metody wywołania usługi (Endpoints)

API obsługuje zapytania typu GET. Poniżej znajdują się dostępne metody strukturyzacji zapytań:

1. Przez identyfikator szukanego obiektu

GET https://uldk.gugik.gov.pl/?request={request}&id={id}&result={result}

2. Przez pełen identyfikator działki lub nazwę obrębu i numer działki

GET https://uldk.gugik.gov.pl/?request=GetParcelByIdOrNr&id={id}&result={result}

3. Wyszukanie obiektu we wskazanym punktu (Przez współrzędne)

GET https://uldk.gugik.gov.pl/?request={request}&xy={xy}&result={result}

4. Snapowanie (Przyciąganie do najbliższego punktu załamania działki)

GET https://uldk.gugik.gov.pl/?request=SnapToPoint&xy={xy}&radius={radius}&result={result}

5. Łączenie geometrii działek o podanych identyfikatorach

GET https://uldk.gugik.gov.pl/?request=GetAggregateArea&id={id}&result={result}

Konsola testowa API

Wybierz metodę, uzupełnij parametry i przetestuj działanie usługi ULDK na żywo.

Generowany URL testowy:
https://uldk.gugik.gov.pl/?request=GetParcelById&id=141201_1.0001.6509&result=id,teryt,parcel,voivodeship&srid=2180
Pobieranie danych z serwera GUGiK...

Parametry zapytania (Query Parameters)

Parametr Typ Opis Wartości / Format / Przykłady
request string wymagany Określa rodzaj operacji oraz poszukiwanego obiektu. Dla identyfikatora / współrzędnych:
GetParcelById / GetParcelByXY - działka
GetBuildingById / GetBuildingByXY - budynek
GetRegionById / GetRegionByXY- obręb (PRG)
GetRegionByNameOrId - obręb po ID lub nazwie TERYT (PRG)
GetCommuneById / GetCommuneByXY gmina (PRG)
GetCountyById / GetCountyByXY - powiat (PRG)
GetVoivodeshipById / GetVoivodeshipByXY - województwo (PRG)
Inne metody:
GetParcelByIdOrNr - działka po indentyfikatorze (np. 141201_1.0001.6509) lub nazwie obrębu i numerze działki (np. Krzewina 134),
SnapToPoint,
GetAggregateArea
id string Identyfikator obiektu lub obiektów (rozdzielone przecinkami dla GetAggregateArea). • Działka: WWPPGG_R.OOOO.[AR_NR.].NR_DZ (np. 141201_1.0001.6509)
• Budynek: WWPPGG_R.OOOO.NR_DZ.Nr_BUD (np. 141301_1.0010.713/2.5_BUD)
• Obręb: WWPPGG_R.OOOO
• Gmina: WWPPGG_R | Powiat: WWPP | Województwo: WW
• Dla GetParcelByIdOrNr dopuszczalne również: Nazwa numer (np. Krzewina 134)
xy string Współrzędne punktu wyszukiwania. Kolejność zgodna z reprezentacją WKT dla wybranego układu. • X,Y - domyślny układ PUWG 1992
• X,Y,SRID - specyficzny układ (np. 460166.4,313380.5,2180)
radius double Promień wyszukiwania w metrach stosowany wyłącznie przy funkcji SnapToPoint. Domyślnie: 1 (np. radius=15)
srid integer Kod EPSG układu współrzędnych, w którym ma zostać zwrócona geometria. Domyślnie: 2180 (PUWG 1992). Przykład: srid=4326
result string Opcjonalny parametr określający zwracane atrybuty (wartości oddzielone przecinkami). geom_wkb - geometria w formacie wbk (domyślny),
geom_wkt - geometria w formacie wbk,
geom_extent - zasięg geometryczny obiektu (bbox),
teryt - identyfikator TERYT obiektu (np. 141201_1.0001.6509),
id - identyfikator TERYT obiektu (np. 141201_1.0001.6509),
function - funkcja (dla budynków),
voivodeship - nazwa województwa,
county - nazwa powiatu,
commune - nazwa gminy ,
region - nazwa obrębu lub numer,
parcel - numer działki,
datasource - informacja o pochodzeniu danych zwróconych przez usługę
Uwagi techniczne:
  • Geometria zwracana jest domyślnie w układzie PUWG 1992 (EPSG:2180).
  • voivodeship, county, commune, region jeśli informacja dot. działki z powiatu nie zawiera takich pól, to są one uzupełniane z PRG

Wyszukiwanie po identyfikatorze lub obrębie i numerze (GetParcelByIdOrNr)

Dla metody GetParcelByIdOrNr w pierwszym wierszu odpowiedzi zwracana jest liczba znalezionych działek.

Wyniki dla wyszukiwania na podstawie nazwy obrębu i numeru działki, nie zawsze są jednoznaczne i w wyniku wyszukiwania można otrzymać więcej działek ze względu na powtarzające się nazwy obrębów, np. zapytanie o działkę 756 w obrębie Stara Wieś:

Wyszukiwnaie po indentyfikatorze lub obrębie i numerze

W przypadku zapytań z nazwą obrębu oprócz wyniku, który może zawierać większą liczbę odpowiedzi trzeba także liczyć się z tym, że czas odpowiedzi może być wydłużony, ponieważ zapytanie musi być obsłużone przez wszystkie powiaty, w których występuje obręb o podanej nazwie. Dla przykładu przy wyszukiwaniu działki „Dąbrowa 12” uzyskujemy w wyniku aż 57 działek spełniających warunki wyszukiwania.

Snapowanie do punktu (SnapToPoint)

Funkcja SnapToPoint oprócz geometrii punktu zwraca również odległość wskazanego punktu od punktu znalezionego.

Snapowanie do punktu

W wyniku zapytania otrzymujemy plik zawierający 3 linie. W pierwszej linii jest status odpowiedzi, w drugiej współrzędne punktu w formacie WKB, a w trzeciej rzeczywista odległość zwróconego punktu od punktu, którego współrzędne podano w wywołaniu usługi.

Agregacja obszarów działek (GetAggregateArea)

Funkcja GetAggregateArea zwraca pojedynczą geometrię typu POLYGON dla działek sąsiadujących, a w przypadku działek niegraniczących ze sobą - MULTIPOLYGON.

Zagregowane działki

Przykłady wykorzystania

1. Wyszukanie działki przez identyfikator (parametry podstawowe)

https://uldk.gugik.gov.pl/?request=GetParcelById&id=141201_1.0001.6509

2. Wyszukanie działki po nazwie obrębu i numerze z określeniem rezultatu

https://uldk.gugik.gov.pl/?request=GetParcelByIdOrNr&id=Krzewina 134&result=id,numer,powiat,geom_wkb

3. Wyszukanie obiektu we wskazanych współrzędnych XY

https://uldk.gugik.gov.pl/?request=GetParcelByXY&xy=460166.4,313380.5

4. Snapowanie do najbliższego punktu załamania

https://uldk.gugik.gov.pl/?request=SnapToPoint&xy=482205,673473

5. Łączenie geometrii dla kilku sąsiadujących działek

https://uldk.gugik.gov.pl/?request=GetAggregateArea&id=141201_1.0001.3912,141201_1.0001.39138

Najczęściej zadawane pytania (FAQ)

Pytanie: Czy korzystanie z usługi ULDK w aplikacji komercyjnej wymaga dodatkowych opłat lub licenji?

Odpowiedź:
Wykorzystanie usługi ULDK w ramach komercyjnej, odpłatnej aplikacji jest w pełni dopuszczalne i nieodpłatne. Nie wymaga również zawierania z GUGiK dodatkowych umów licencyjnych.

Pytanie: Czy wykorzystanie usługi ULDK wymaga podawania źródła pochodzenia danych na stronie/w aplikacji?

Odpowiedź:
Koniecznym jest podanie źródła np. w postaci atrybucji „Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Usługa Lokalizacji Działek Katastralnych (ULDK).” lub w innej formie wskazującej źródło pozyskania danych.

Pytanie: Czy istnieją inne źródla pozwalające na dostęp do danych EGiB w skali całego kraju?

Odpowiedź:
Dane dotyczące działek i budynków są również dostępne za pośrednictwem paczek danych w formatach geoparquet oraz gpkg z modułu „Pobierz dane” w serwisie geoportal.gov.pl, dane są grupowane według podziału administracyjnego na paczkę dla kraju, paczki dla województw i indywidualnych powiatów.

GUGiK udostępnia również pobrane dane z powiatowych usług WFS w skali całego kraju w ramach jednej zbiorczej usługi pobierania WFS EGiB: https://mapy.geoportal.gov.pl/wss/service/PZGIK/EGIB/WFS/UslugaZbiorcza

Pytanie: Czy korzystanie z usługi ULDK w większej skali wymaga rejestracji lub uzyskania klucza API?

Odpowiedź:
Standardowe korzystanie z usługi ULDK nie wymaga rejestracji, zgłoszenia ani uzyskiwania kluczy API.

Jeżeli jednak przewidywane, że ruch produkcyjny aplikacji będzie regularnie przekraczał standardowe limity zapytań, istnieje możliwość bezpłatnego zgłoszenia adresów IP do białej listy (listy zaufanej).

Aktualne limity dla użytkowników nieznajdujących się na białej liście to 200 zapytań w ciągu minuty w godzinach między 6- 18 oraz 40 zapytań na minutę w pozostałych godzinach, przy czym łączna liczba zapytań w ciągu doby na jedno IP jest ograniczona do 10 000 zapytań.

Istnieje możliwość zgłoszenia wykorzystywanych do zapytań adresów IP do białej listy, której nie dotyczą powyższe limity. Procedura realizowana jest w formie wiadomości przesłanej bezpośrednio na adres e-mail: uslugi.iip@gugik.gov.pl. Główny Urząd Geodezji i Kartografii nie wymaga stosowania dedykowanego szablonu czy formularza urzędowego.

Wniosek powinien zostać wysłany przez osobę upoważnioną do reprezentowania organizacji lub kierownika projektu IT, z zachowaniem oficjalnej stopki teleadresowej firmy.

W celu sprawnej realizacji zgłoszenia prosimy o wskazanie w treści wiadomości: pełnych adresów IP (lub zakresów w notacji CIDR), które mają zostać objęte regułą białej listy oraz ewentualnych danych kontaktowych do administratora technicznego po stronie Państwa firmy.

Wprowadzenie adresów IP na listę ma na celu wyłączenie Państwa ruchu produkcyjnego ze standardowych mechanizmów ochrony wydajnościowej (tzw. rate limiting). Standardowe limity są wprowadzane w celu zapobiegania przeciążeniom serwerów oraz atakom typu DDoS. Wpisanie na listę zaufaną pozwoli Państwa systemom na stabilną realizację zapytań przekraczających standardowe progi bezpieczeństwa.

Pytanie: Co jest źródłem danych zwracanych przez ULDK?

Odpowiedź:
Mechanizm działania usługi ULDK dla działek przedstawia się w następujący sposób:

  1. ULDK odpytuje powiatową usługę pobierania (WFS) zgłoszoną dla zbioru Ewidencja Gruntów i Budynków (EGiB) do ewidencji zbiorów i usług danych przestrzennych, która jest włączona do usługi ULDK o działkę, np. poprzez wskazania jej identyfikatora przez użytkownika usługi ULDK. Jeżeli działka jest dostępna w usłudze powiatowej WFS EGiB włączonej do ULDK, geometria wraz z atrybutami działki zwracana jest z usługi powiatowej.
  2. W sytuacji, gdy usługa powiatowa WFS EGiB włączona do usługi ULDK nie działa, zapytanie o działkę przez usługę ULDK przekierowane jest do bazy danych, z której korzysta usługa pobierania danych ewidencji gruntów i budynków (WFS), wówczas geometria wraz z atrybutami działki zwracana jest z bazy tej usługi. Wdrożenie tego rozwiązania miało na celu zapewnienie ciągłości działania funkcjonalności usługi ULDK w sytuacji, gdy usługa powiatowa WFS EGiB zintegrowana z usługą ULDK nie działa w momencie wysyłania do niej przez usługę ULDK zapytania o działkę. Jeżeli działka jest niedostępna w usłudze powiatowej WFS EGiB, nie będzie ona również dostępna w bazie usługi pobierania danych ewidencji gruntów i budynków (WFS).
  3. Należy zaznaczyć również, że niektóre powiaty w kraju nie posiadają pełnego pokrycia danymi wektorowymi na obszarze całego powiatu. W usłudze ULDK są zdefiniowane powiaty nieposiadające pełnego pokrycia danymi wektorowymi. Wówczas w przypadku zapytania o działkę z obszaru powiatu nieposiadającego pełnego stopnia pokrycia danymi wektorowymi, usługa ULDK sprawdza dostępność działki w pierwszej kolejności w powiatowej usłudze pobierania (WFS), kolejno w bazie danych, z której korzysta usługa pobierania danych ewidencji gruntów i budynków (WFS), a w ostatnim, trzecim kroku usługa ULDK odpytuje bazę LPIS (System Identyfikacji Działek Rolnych), która jest podłączona do usługi ULDK i w przypadku dostępności działki w tej bazie, usługa ULDK zwraca geometrię działki z bazy LPIS.
Przepływ ULDK

Więcej informacji o zbiorach EGiB

Szczegółowe opisy oraz dodatkową dokumentację opublikowano na oficjalnej stronie Geoportalu:

https://www.geoportal.gov.pl/pl/dane/ewidencja-gruntow-i-budynkow-egib