Geokodowanie odwrotne — znajdź adres po współrzędnych GPS

Masz współrzędne GPS i potrzebujesz nazwy ulicy? Dowiedz się, jak działa geokodowanie odwrotne oparte na PostGIS i jak zintegrować endpoint /api/v1/reverse z aplikacją mobilną lub systemem IoT.

Geokodowanie odwrotne (ang. reverse geocoding) to zamiana pary współrzędnych geograficznych na czytelny adres. Jeśli Twoja aplikacja mobilna, urządzenie IoT lub system logistyczny zna pozycję GPS, możesz w ciągu milisekund uzyskać pełny adres pocztowy z numerem budynku, kodem pocztowym i przypisaniem do gminy.

Jak działa /api/v1/reverse

Endpoint GET /api/v1/reverse korzysta z bazy PRG (Państwowy Rejestr Granic) przechowującej ponad 15 milionów punktów adresowych w układzie WGS84. Silnik to PostGIS z indeksem KNN (K Nearest Neighbor) — zapytanie wyszukuje najbliższy punkt adresowy bez skanowania całej tabeli.

Wynik zawiera pole score w skali 0–1: 1,0 oznacza trafienie dokładnie na centroid budynku, wartości bliskie 0 — punkt na granicy zadanego promienia. Pozwala to szybko odfiltrować wątpliwe dopasowania.

Parametry

Endpoint przyjmuje cztery parametry: lat i lon (WGS84, Polska: 49–54,9°N, 14,1–24,2°E), radius (promień w metrach, domyślnie 500, max 5000) oraz limit (liczba wyników 1–10, domyślnie 1).

Zastosowania

Aplikacje mobilne — wyświetl użytkownikowi jego aktualny adres bez konieczności wpisywania
Logistyka i kurierzy — przypisz zgłoszenie GPS kierowcy do konkretnego punktu adresowego PRG
IoT i czujniki — urządzenie z GPS przesyła log lokalizacji; backend zamienia go na adres
Mapy interaktywne — kliknięcie na mapę zwraca pełny adres do formularza
Geofencing — sprawdź, czy punkt GPS mieści się w zasięgu adresu (pole distance_m)

Przykład w JavaScript — kliknięcie na mapę Leaflet wypełnia formularz adresowy jednym zapytaniem /api/v1/reverse.

Pełna dokumentacja endpointu →

FAQ

Jaka jest dokładność geokodowania odwrotnego?

PRG przechowuje centroidy budynków, więc dokładność wynosi zwykle 5–30 m. Endpoint zwraca pole distance_m — jeśli jest poniżej 50 m i score powyżej 0,9, dopasowanie jest pewne. Dla punktów poza obszarami zabudowanymi wynik może być odległy o setki metrów.

Co zwraca endpoint gdy w promieniu nie ma żadnego adresu?

Pole found ma wartość false, tablica results jest pusta. Zalecanym zachowaniem jest zwiększenie promienia (do max 5000 m) lub wyświetlenie komunikatu o braku adresu w pobliżu.

Czy endpoint obsługuje współrzędne poza Polską?

Nie — zapytania poza zakresem 49–54,9°N i 14,1–24,2°E zwracają błąd HTTP 422. Baza PRG obejmuje tylko Polskę.

Ile kosztuje użycie /api/v1/reverse?

Endpoint liczy się jak każde inne zapytanie — wlicza się w limit req/min i miesięczny limit planu. Plan Free obsługuje 3 req/min, Starter 200 req/min.