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ło | Współrzędne w odpowiedzi | Wymagany klucz API |
|---|---|---|---|
GET /api/v1/prg/autocomplete | PRG (Państwowy Rejestr Granic, punkty adresowe) → fallback do TERYT | tak (lat / lon) | nie |
GET /api/v1/teryt/autocomplete | TERYT (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/autocompletejest 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
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
q | string | tak | Fraza 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:
| Pole | Typ | Opis |
|---|---|---|
city | string | Nazwa miejscowości. |
street | string? | Nazwa ulicy (bez przedrostka ul.). null gdy wynik to tylko miejscowość. |
house_number | string? | Numer budynku (gdy znaleziono w PRG). |
lat / lon | float? | Współrzędne EPSG:4326. null gdy wynik pochodzi z fallbacku TERYT. |
gmina | string? | Nazwa gminy (obecnie pusta — pole zarezerwowane). |
teryt_gmi | string? | Identyfikator TERYT gminy (obecnie pusta — pole zarezerwowane). |
source | string | Ź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
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
q | string | tak | Fraza 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:
| Pole | Typ | Opis |
|---|---|---|
city | string | Nazwa miejscowości (dla dużych miast np. Wrocław zamiast Wrocław-Fabryczna). |
street | string? | Nazwa ulicy. null gdy wynik to tylko miejscowość. |
sym | string | Identyfikator SIMC miejscowości (TERYT). |
sym_ul | string? | 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:
- Czyszczenie przedrostków — fraza jest czyszczona z typowych przedrostków ulic (
ul.,ulica,al.,aleja,pl.,plac,os.,osiedle). Wpisz po prostuLegnicka 12zamiastul. Legnicka 12. - Format zapytania — obsługiwane są cztery warianty:
- Jedno słowo (
Wrocław) → podpowiedź miejscowości (i ulic, gdy znajdzie). - Przecinek (
Wrocław, LegnickaalboLegnicka, Wrocław) → najpierw próbuje wariantuMiasto, Ulica, potem odwrotnego. - Fraza bez przecinka (
Wrocław Legnicka) → próbuje interpretacjipierwsze słowo = miasto, reszta = ulica, a następnie odwrotnie.
- Jedno słowo (
- 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 |
|---|---|---|
| Dane | Punkty adresowe PRG (z numerami budynków i współrzędnymi) | Rejestr TERYT (miejscowości SIMC + ulice ULIC) |
| Współrzędne | Tak, gdy wynik z PRG | Nie |
| Numery budynków | Tak (house_number) | Nie |
| Identyfikatory TERYT | teryt_gmi (gmina) | sym (SIMC), sym_ul (ULIC) |
| Fallback | Do TERYT, gdy brak wyników w PRG | Brak (to ostateczne źródło) |
| Typowe zastosowanie | Geokodowanie na mapie, dalsza analiza | Budowa adresów z oficjalnych rejestrów |
Obsługa błędów
- 422 — brak parametru
qlub 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
- Location Intelligence Model (LIM) — pełny raport B2B, gdy masz już współrzędne z autocomplete.
- Automatyczna wycena (AVM) — benchmark ceny ofertowej dla adresu.
- Wskaźnik zazielenienia — szybki wskaźnik zieleni dla działki.
- Dokumentacja API — interaktywna konsola Swagger UI ze schematami
AutocompleteSuggestioniPrgAutocompleteSuggestion. - Uwierzytelnianie — choć autocomplete jest publiczny, inne endpointy wymagają klucza Bearer.