Addresses Lookup API

Polskie adresy, kody pocztowe i rejestr TERYT — JSON REST API dla integratorów

Opis

Addresses Lookup to hosted API oparte o oficjalne dane TERYT (GUS) oraz przypisania kodów pocztowych ze Spisu PNA. W przeciwieństwie do prostych API typu kodpocztowy.intami.pl oferuje m.in.:

Format odpowiedzi: application/json. Autentykacja i plany subskrypcji obsługuje RapidAPI.

Subskrybuj na RapidAPI Dokumentacja OpenAPI

API

Wywołania produkcyjne przechodzą przez bramę RapidAPI. Nagłówki X-RapidAPI-Key i X-RapidAPI-Host otrzymasz po subskrypcji w panelu RapidAPI. Poniżej przykłady — zamień host i klucz na wartości z Twojej aplikacji.

Autocomplete (ulice + miejscowości)

curl --request GET \
  --url 'https://address-lookup.p.rapidapi.com/v1/autocomplete/unified?q=wroc&limit=10' \
  --header 'X-RapidAPI-Key: TWOJ_KLUCZ' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'

Kod pocztowy — pełna lista przypisań

curl --request GET \
  --url 'https://address-lookup.p.rapidapi.com/v1/postal-codes/50-001' \
  --header 'X-RapidAPI-Key: TWOJ_KLUCZ' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'

Kody pocztowe miasta

curl --request GET \
  --url 'https://address-lookup.p.rapidapi.com/v1/cities/Wroc%C5%82aw/postal-codes' \
  --header 'X-RapidAPI-Key: TWOJ_KLUCZ' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'

Kody pocztowe — dzielnica

curl --request GET \
  --url 'https://address-lookup.p.rapidapi.com/v1/cities/Wroc%C5%82aw/districts/Opor%C3%B3w/postal-codes' \
  --header 'X-RapidAPI-Key: TWOJ_KLUCZ' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'

Kody pocztowe — ulica w mieście

curl --request GET \
  --url 'https://address-lookup.p.rapidapi.com/v1/cities/Wroc%C5%82aw/streets/Grodzka/postal-codes' \
  --header 'X-RapidAPI-Key: TWOJ_KLUCZ' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'

Pełny adres (TERYT sym + opcjonalnie symUl)

curl --request GET \
  --url 'https://address-lookup.p.rapidapi.com/v1/addresses/resolve?sym=0986280&symUl=12345' \
  --header 'X-RapidAPI-Key: TWOJ_KLUCZ' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'

Hierarchia regionów — województwa

curl --request GET \
  --url 'https://address-lookup.p.rapidapi.com/v1/regions/provinces' \
  --header 'X-RapidAPI-Key: TWOJ_KLUCZ' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'
Endpointy
  • GET /v1/autocomplete/localities, streets, postal-codes, unified
  • GET /v1/postal-codes/:code
  • GET /v1/cities/:city/postal-codes
  • GET /v1/cities/:city/districts/:district/postal-codes
  • GET /v1/cities/:city/streets/:street/postal-codes
  • GET /v1/addresses/resolve, /v1/addresses/resolve-by-path
  • GET /v1/regions/provinces → counties → communes → localities → streets

Pełna specyfikacja parametrów i schematów JSON: Swagger UI.

Opis pól (przypisanie pocztowe)

Typowy element tablicy data przy lookup kodu pocztowego lub miasta:

Pole JSON Opis Wymagalność
postalCode Kod pocztowy (format xx-xxx) zawsze
locality Miejscowość zawsze
street Ulica opcjonalnie
district Dzielnica (w miastach wielodzielnicowych) opcjonalnie
commune Gmina zawsze
county Powiat zawsze
province Województwo zawsze
numbering Opis numeracji (np. numery parzyste) opcjonalnie

Autocomplete zwraca skrócone obiekty z polem label gotowym do wyświetlenia w formularzu. Resolve zwraca pełny adres z kodami TERYT.

Demo

Wpisz fragment nazwy miejscowości lub ulicy (min. 2 znaki):

Wynik pojawi się tutaj (JSON).

Demo korzysta z API w tle. W produkcji wymaga skonfigurowanego proxy RapidAPI. Do pełnych testów użyj konsoli testowej na RapidAPI po subskrypcji.

OpenAPI

Interaktywna dokumentacja (Swagger UI) jest dostępna pod adresem origin API — przydatna przy integracji i imporcie definicji do RapidAPI Hub.

Otwórz Swagger UI Pobierz openapi.json

Plany i limity

Limity zapytań i ceny ustawiasz w panelu RapidAPI (plany Basic / Pro / Ultra). Szczegóły w pliku docs/RAPIDAPI-SETUP.md w repozytorium projektu.