Widget adresowy do formularzy
Jedna linijka kodu dodaje do formularza podpowiadanie adresów z rejestru PRG i automatyczne wypełnianie kodu pocztowego, miejscowości, ulicy, numeru, kodów TERYT i współrzędnych. Do sklepów internetowych, CRM, formularzy zgłoszeniowych.
Wypróbuj
1. Najprostsza instalacja — bez pisania JavaScriptu
Wklej przed </body>. Atrybut data-input to selektor pola adresu, a data-fill-* mówią, które pola wypełnić po wyborze.
<input id="adres" placeholder="Zacznij wpisywać adres…">
<input id="kod" placeholder="Kod pocztowy"> <input id="miasto" placeholder="Miejscowość">
<script src="https://polskieadresy.pl/widget.js"
data-input="#adres" data-key="TWÓJ_KLUCZ"
data-fill-kod_pocztowy="#kod" data-fill-miejscowosc="#miasto"
data-fill-ulica="#ulica" data-fill-numer="#numer"></script>2. Sterowanie z kodu
<script src="https://polskieadresy.pl/widget.js"></script>
<script>
const w = PolskieAdresy.attach(document.querySelector('#adres'), {
key: 'TWÓJ_KLUCZ', // opcjonalnie; bez klucza obowiązują limity anonimowe per IP odwiedzającego
typ: null, // 'miejscowosc' albo 'ulica' — ogranicza podpowiedzi
requireSelect: true, // zaznacz pole na czerwono, jeśli użytkownik nic nie wybrał
onSelect(wynik) {
console.log(wynik.kod_pocztowy, wynik.teryt.simc, wynik.lat, wynik.lon);
},
});
// później: w.selected (wybrany obiekt lub null), w.clear()
</script>3. Walidacja adresu przed wysłaniem formularza
Gdy użytkownik wpisał adres ręcznie, bez wybierania podpowiedzi, sprawdź go geokoderem:
form.addEventListener('submit', async (e) => {
e.preventDefault();
const r = await PolskieAdresy.geocode(adres.value, 'TWÓJ_KLUCZ');
if (r.status !== 'dopasowano') return alert('Sprawdź adres: ' + adres.value);
// r.wynik.kod_pocztowy, r.wynik.adres, r.score
form.submit();
});Opcje
| Atrybut / opcja | Opis |
|---|---|
data-input | Selektor CSS pola (może pasować do kilku pól) |
data-key / key | Klucz API z panelu (opcjonalny) |
data-typ / typ | miejscowosc lub ulica — tylko taki rodzaj podpowiedzi |
data-fill-POLE / fill | Selektor pola do wypełnienia wartością POLE z odpowiedzi (zagnieżdżone przez myślnik: teryt-simc) |
data-require="1" / requireSelect | Podświetl pole na czerwono, jeśli nie wybrano podpowiedzi |
data-limit / limit | Liczba podpowiedzi (domyślnie 8) |
data-branding="0" / branding:false | Ukryj podpis „PolskieAdresy.pl” pod listą (plany płatne) |
| zdarzenia | polskieadresy:select (event.detail = wynik), polskieadresy:clear |
Co dostajesz po wyborze adresu
Pełny obiekt adresu z API: sformatowany adres, kod pocztowy i pocztę, ulicę i numer, miejscowość, dzielnicę, gminę, powiat, województwo, kody TERYT (SIMC, ULIC, TERC), współrzędne WGS84 i identyfikator PRG. Format opisuje dokumentacja API.
Najczęstsze pytania
Czy widget działa bez klucza API?
Tak. Bez klucza zapytania są liczone per adres IP odwiedzającego (limit anonimowy), co zwykle wystarcza w małym sklepie. Z kluczem limity liczą się na Twoim koncie, a przy większym ruchu wybierasz odpowiedni plan.
Czy klucz API w kodzie strony jest bezpieczny?
Utwórz w panelu klucz z listą dozwolonych domen (np. sklep.pl, *.sklep.pl). Taki klucz działa tylko na Twoich stronach — zapytania z innych domen lub spoza przeglądarki są odrzucane. Klucz nie daje dostępu do konta i można go w każdej chwili unieważnić.
Jakie pola może wypełniać widget?
Dowolne pole odpowiedzi API: adres, ulica, numer, kod_pocztowy, poczta, miejscowosc, gmina, powiat, wojewodztwo, lat, lon, teryt-simc, teryt-ulic, teryt-terc, id, id_prg. Wystarczy atrybut data-fill-NAZWA="#selektor".
Czy widget zmienia wygląd mojego formularza?
Nie. Dodaje tylko listę podpowiedzi pod polem (własne, prefiksowane klasy CSS) i nie ładuje żadnych zewnętrznych bibliotek. Rozmiar: około 6 KB.