Walidacja adresu w formularzu — jak poprawnie zbierać adresy

Jak wdrożyć walidację adresów w formularzach web? Autocomplete, weryfikacja kodu pocztowego, sprawdzanie numeru budynku — praktyczny poradnik dla programistów i właścicieli sklepów internetowych.

Problem: klienci wpisują błędne adresy

Każdy sklep internetowy zna ten problem — klient wpisuje adres ręcznie i popełnia błąd: literówka w nazwie ulicy, zły kod pocztowy, brakujący numer budynku. Efekt? Zwroty przesyłek, opóźnienia, koszty kuriera i niezadowoleni klienci.

Według badań branżowych nawet 10–15% adresów w bazach e-commerce zawiera błędy. Przy tysiącach zamówień miesięcznie to setki zwrotów.

Rozwiązanie: walidacja adresu w czasie rzeczywistym

Zamiast pozwalać klientowi wpisać dowolny tekst, warto walidować adres na bieżąco — w momencie wypełniania formularza. Trzy metody:

1. Autocomplete (podpowiedzi adresowe)

Najskuteczniejsza metoda. Klient zaczyna wpisywać adres, a system podpowiada pasujące adresy z bazy PRG. Klient wybiera z listy — co eliminuje literówki i zapewnia kompletne dane.

GET /api/v1/autocomplete?q=Kosciuszki+14+Wro&limit=5

Odpowiedź zawiera pełne adresy z kodem pocztowym, TERYT i współrzędnymi — wystarczy wstawić do formularza.

2. Weryfikacja po wypełnieniu

Klient wypełnia formularz tradycyjnie, a system sprawdza adres z bazą PRG po kliknięciu „Dalej". Jeśli adres nie istnieje — wyświetl komunikat z propozycją poprawki.

3. Walidacja kodu pocztowego

Minimum: sprawdzenie, czy podany kod pocztowy pasuje do miejscowości i ulicy. W Polsce jeden budynek = jeden kod pocztowy, więc niezgodność oznacza błąd.

Implementacja z Adresy.app API

Przykład zapytania autocomplete:

GET /api/v1/autocomplete?q=Kosciuszki+14+Wro&limit=5
Host: api.adresy.app
X-API-Key: TWOJ_KLUCZ

Odpowiedź zawiera listę pasujących adresów z kodem pocztowym, TERYT i współrzędnymi — wystarczy wstawić do pól formularza. Dodaj debounce (200 ms), żeby nie wysyłać zapytania przy każdym klawiszu.

Co walidować?

Pole	Walidacja formatu	Weryfikacja z PRG
Kod pocztowy	Format XX-XXX	Czy pasuje do adresu
Miejscowość	Niepusty tekst	Czy istnieje w TERYT SIMC
Ulica	Niepusty tekst	Czy istnieje w TERYT ULIC dla tej miejscowości
Numer budynku	Format liczbowy/alfanumeryczny	Czy istnieje punkt adresowy w PRG

Korzyści biznesowe

Mniej zwrotów — prawidłowy adres = udane doręczenie
Czystsza baza — dane klientów od razu znormalizowane
Szybszy checkout — autocomplete przyspiesza wypełnianie formularza
Niższe koszty — mniej reklamacji, mniej korekt faktur
Dane do analiz — TERYT i współrzędne dają możliwość analiz logistycznych i marketingowych

FAQ

Ile kosztuje walidacja adresów przez API?

Plan Free daje 30 zapytań/min i 3 000 zapytań/miesiąc bez opłat — wystarczy do testów i małych sklepów. Plan Starter (39 zł/mies) to 200 req/min i 100 tys. zapytań miesięcznie, Business (299 zł/mies) — 10 mln zapytań i 1 200 req/min.

Czy autocomplete spowalnia stronę?

Nie — odpowiedź API trwa poniżej 50 ms. Warto dodać debounce (np. 200 ms) żeby nie wysyłać zapytania przy każdym naciśnięciu klawisza.

Czy muszę wyświetlać autocomplete, czy mogę walidować po wysłaniu formularza?

Oba podejścia działają. Autocomplete jest lepsze UX-owo (mniej błędów), ale walidacja po wysłaniu też znacząco redukuje błędy.

Jak obsłużyć adresy firmowe z nazwą firmy?

API ignoruje prefiks firmy — wystarczy podać sam adres (ulica, numer, miejscowość). Nazwę firmy przechowuj w osobnym polu formularza.