Główny Urząd Geodezji i Kartografii

Specyfikacja usługi ULDK

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.

Parametr request (Operacja)

Identyfikator (id)

Współrzędne (xy)

Identyfikator (id)

Promień wyszukiwania (radius w metrach)

Zwracane atrybuty (result - opcjonalnie, rozdzielane przecinkiem)

Układ współrzędnych wyników (srid)

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

Odpowiedź z serwera:

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.

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.

Przykłady wykorzystania

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.

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