Autocomplete adresu w 3 krokach: miejscowość → ulica → numer

Jak zbudować płynne autouzupełnianie polskiego adresu za pomocą trzech endpointów API — bez żadnych zewnętrznych bibliotek. Z przykładami w JavaScript i React.

Autouzupełnianie adresu to jeden z najważniejszych elementów formularza zakupowego. Użytkownik, który trafi na niedziałający dropdown z ulicami lub musi sam wpisać kod pocztowy, porzuca koszyk. API Adresy.app dostarcza kompletny trójstopniowy flow oparty na oficjalnych rejestrach TERYT i PRG.

Jak to działa — cztery wywołania

  1. /miejscowosci?q=wrocł — użytkownik wpisuje fragment nazwy miasta, dostajesz listę z kodami SIMC
  2. /ulice?sym=SIMC&q=ryn — po wybraniu miejscowości wpisujesz ulicę, dostajesz kody ULIC
  3. /numery?sym=SIMC&sym_ul=ULIC — po wybraniu ulicy dostajesz numery budynków z PRG
  4. /lookup/autofill?sym=SIMC&sym_ul=ULIC&nr=1 — jednym zapytaniem wypełniasz kod pocztowy, gminę, powiat, województwo i GPS

Krok 1 — miejscowości

GET /api/v1/miejscowosci?q=wrocł&limit=10 — już 2 znaki dają wyniki. Zwracane pole sym (SIMC) jest potrzebne do kolejnych kroków.

Krok 2 — ulice

GET /api/v1/ulice?sym=0986283&q=ryn — parametr sym to SIMC miejscowości z kroku 1. Zwracane sym_ul (ULIC) potrzebne do kroku 3.

Krok 3 — numery budynków

GET /api/v1/numery?sym=0986283&sym_ul=18834 — zwraca tablicę numerów budynków z PRG dla danej ulicy.

Krok 4 — autofill

GET /api/v1/lookup/autofill?sym=0986283&sym_ul=18834&nr=1 — jedno wywołanie wypełnia: ulicę, numer, miejscowość, kod pocztowy, gminę, powiat, województwo i współrzędne GPS. Eliminuje ręczne wpisywanie kodu pocztowego i redukuje błędy adresowe do zera.

Wszystkie cztery endpointy wymagają planu Starter lub wyższego (capability autocomplete). Zobacz plany →

FAQ

Czy autocomplete wymaga rejestracji?
Tak — endpointy /miejscowosci, /ulice, /numery i /lookup/autofill wymagają klucza API z planem Starter lub wyższym. Plan Free nie zawiera capability autocomplete.
Jak unikać zbędnych zapytań podczas wpisywania?
Używaj debounce — wywołaj API najwcześniej po 300 ms od ostatniego znaku. Możesz też cachować wyniki dla tego samego sym (SIMC) — lista ulic w danej miejscowości zmienia się co miesiąc.
Czy API obsługuje CORS dla zapytań z przeglądarki?
Tak — CORS jest otwarty dla wszystkich domen. Klucz API przekazujesz w nagłówku X-API-Key, nie w URL, więc jest bezpieczny w ruchu HTTPS.
Co z adresami bez nazwy ulicy?
Dla miejscowości bez ulic /ulice zwraca pustą listę, a /numery zwraca bezpośrednio numery z PRG. Autofill działa poprawnie — wystarczy sym i nr, bez sym_ul.