Skip to Content
Przewodniki integracjiAutocomplete adresów

Autocomplete adresów

Autocomplete adresów to szybkie, publiczne wyszukiwanie podpowiedzi (miejscowości i ulic) dla całej Polski. Służy do implementacji pola „wpisz adres” w formularzach, mapach i wyszukiwarkach nieruchomości — dokładnie tak, jak na landing page LokalScore.

Dostępne są dwa endpointy GET, które różnią się źródłem danych i zawartością odpowiedzi:

EndpointŹródłoWspółrzędne w odpowiedziWymagany klucz API
GET /api/v1/prg/autocompletePRG (Państwowy Rejestr Granic, punkty adresowe) → fallback do TERYTtak (lat / lon)nie
GET /api/v1/teryt/autocompleteTERYT (rejestr TERYT: SIMC + ULIC)nie (tylko identyfikatory sym / sym_ul)nie

Rekomendacja: Używaj /prg/autocomplete, gdy potrzebujesz współrzędnych od razu w podpowiedzi (np. do dalszej analizy lokalizacji). /teryt/autocomplete jest lżejszy i zwraca oficjalne identyfikatory TERYT — przydatny, gdy chcesz budować adresy z danych urzędowych.

Oba endpointy są publiczne — nie wymagają klucza API i mogą być wywoływane bezpośrednio z przeglądarki (co robi landing page). Podlegają jednak standardowym limitom zapytań (rate limiting per-IP).


GET /api/v1/prg/autocomplete

Autouzupełnianie adresów z priorytetem PRG (punkty adresowe z współrzędnymi). Wyszukuje podpowiedzi najpierw w tabeli prg_address_points, a jeśli nie znajdzie wyników — robi fallback do TERYT. Gdy wynik pochodzi z PRG, odpowiedź zawiera współrzędne lat / lon.

Parametry zapytania

ParametrTypWymaganyOpis
qstringtakFraza wyszukiwania. Minimum 2 znaki. Obsługuje formaty: Miasto, Miasto, Ulica, Ulica, Miasto, Miasto Ulica.

Przykład wywołania

curl -X 'GET' \ 'https://api.lokalscore.pl/api/v1/prg/autocomplete?q=Wroc%C5%82aw%2C%20Legnicka'

Struktura odpowiedzi

Każda podpowiedź to obiekt PrgAutocompleteSuggestion:

PoleTypOpis
citystringNazwa miejscowości.
streetstring?Nazwa ulicy (bez przedrostka ul.). null gdy wynik to tylko miejscowość.
house_numberstring?Numer budynku (gdy znaleziono w PRG).
lat / lonfloat?Współrzędne EPSG:4326. null gdy wynik pochodzi z fallbacku TERYT.
gminastring?Nazwa gminy (obecnie pusta — pole zarezerwowane).
teryt_gmistring?Identyfikator TERYT gminy (obecnie pusta — pole zarezerwowane).
sourcestringŹródło wyniku: prg (punkty adresowe z współrzędnymi) lub teryt (fallback bez współrzędnych).

Przykład odpowiedzi

[ { "city": "Wrocław", "street": "Legnicka", "house_number": "12", "lat": 51.1093, "lon": 17.0289, "gmina": null, "teryt_gmi": null, "source": "prg" } ]

GET /api/v1/teryt/autocomplete

Autouzupełnianie adresów (miejscowość i ulica) na podstawie bazy TERYT (SIMC dla miejscowości, ULIC dla ulic) z użyciem indeksów trigramowych. Nie zwraca współrzędnych — tylko oficjalne nazwy i identyfikatory.

Parametry zapytania

ParametrTypWymaganyOpis
qstringtakFraza wyszukiwania. Minimum 2 znaki. Obsługuje formaty: Miasto, Miasto, Ulica, Ulica, Miasto, Miasto Ulica.

Przykład wywołania

curl -X 'GET' \ 'https://api.lokalscore.pl/api/v1/teryt/autocomplete?q=Boles%C5%82awiec'

Struktura odpowiedzi

Każda podpowiedź to obiekt AutocompleteSuggestion:

PoleTypOpis
citystringNazwa miejscowości (dla dużych miast np. Wrocław zamiast Wrocław-Fabryczna).
streetstring?Nazwa ulicy. null gdy wynik to tylko miejscowość.
symstringIdentyfikator SIMC miejscowości (TERYT).
sym_ulstring?Identyfikator ULIC ulicy (TERYT). null gdy wynik to tylko miejscowość.

Przykład odpowiedzi

[ { "city": "Bolesławiec", "street": null, "sym": "0937239", "sym_ul": null } ]

Jak działa wyszukiwanie?

Oba endpointy przetwarzają zapytanie w podobny, elastyczny sposób:

  1. Czyszczenie przedrostków — fraza jest czyszczona z typowych przedrostków ulic (ul., ulica, al., aleja, pl., plac, os., osiedle). Wpisz po prostu Legnicka 12 zamiast ul. Legnicka 12.
  2. Format zapytania — obsługiwane są cztery warianty:
    • Jedno słowo (Wrocław) → podpowiedź miejscowości (i ulic, gdy znajdzie).
    • Przecinek (Wrocław, Legnicka albo Legnicka, Wrocław) → najpierw próbuje wariantu Miasto, Ulica, potem odwrotnego.
    • Fraza bez przecinka (Wrocław Legnicka) → próbuje interpretacji pierwsze słowo = miasto, reszta = ulica, a następnie odwrotnie.
  3. Deduplikacja — podpowiedzi są deduplikowane po parze (miasto, ulica); dla ulic nie powiela się różnych numerów budynków.

Różnice między PRG a TERYT

Aspekt/prg/autocomplete/teryt/autocomplete
DanePunkty adresowe PRG (z numerami budynków i współrzędnymi)Rejestr TERYT (miejscowości SIMC + ulice ULIC)
WspółrzędneTak, gdy wynik z PRGNie
Numery budynkówTak (house_number)Nie
Identyfikatory TERYTteryt_gmi (gmina)sym (SIMC), sym_ul (ULIC)
FallbackDo TERYT, gdy brak wyników w PRGBrak (to ostateczne źródło)
Typowe zastosowanieGeokodowanie na mapie, dalsza analizaBudowa adresów z oficjalnych rejestrów

Obsługa błędów

  • 422 — brak parametru q lub zbyt krótka fraza (< 2 znaki). Zbyt krótka fraza zwraca pustą listę [].
  • 429 — przekroczony limit zapytań (rate limit per-IP).
  • 504 — przekroczony limit czasu przy złożonych zapytaniach trigramowych.

Uwaga: Zapytania trigramowe bywają kosztowne przy dużych frazach. Wyniki dla jednoznacznych, krótkich fraz są zwracane w milisekundach, ale bardzo ogólne, wielowyrazowe zapytania (np. samo a) mogą zwrócić pustą listę lub działać wolniej.


Następne kroki

LokalScore
System scoringu lokalizacji i wyceny nieruchomości w Polsce.
© 2026 LokalScore. Wszelkie prawa zastrzeżone.