Addresses Lookup API

Polish addresses, postal codes, and the TERYT registry — JSON REST API for integrators

Overview

Addresses Lookup is a hosted API built on official TERYT (GUS) data and postal code assignments from the PNA register. It offers:

Response format: application/json. Authentication and subscription plans are handled by RapidAPI.

Subscribe on RapidAPI OpenAPI documentation

API

Production requests go through the RapidAPI gateway. You receive the X-RapidAPI-Key and X-RapidAPI-Host headers after subscribing in the RapidAPI dashboard. Examples below — replace the host and key with values from your app.

Autocomplete (streets + localities)

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

Postal code — full assignment list

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

City postal codes

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

Postal codes — district

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: YOUR_KEY' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'

Postal codes — street in city

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

Full address (TERYT sym + optional symUl)

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

Region hierarchy — provinces

curl --request GET \
  --url 'https://address-lookup.p.rapidapi.com/v1/regions/provinces' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: address-lookup.p.rapidapi.com'
Endpoints
  • 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

Full parameter and JSON schema specification: Swagger UI.

Response fields (postal assignment)

Typical element of the data array for a postal code or city lookup:

JSON field Description Required
postalCode Postal code (format xx-xxx) always
locality Locality always
street Street optional
district District (in multi-district cities) optional
commune Commune (gmina) always
county County (powiat) always
province Province (województwo) always
numbering Numbering description (e.g. even numbers only) optional

Autocomplete returns compact objects with a label field ready for form display. Resolve returns a full address with TERYT codes.

Demo

Start typing a locality or street name (min. 2 characters):

Select a suggestion to view the API response (JSON).

The demo calls the API in the background. In production it requires a configured RapidAPI proxy. For full testing, use the test console on RapidAPI after subscribing.

OpenAPI

Interactive documentation (Swagger UI) is available at the API origin — useful for integration and importing the definition into RapidAPI Hub.

Open Swagger UI Download openapi.json

Plans and limits

Request limits and pricing are configured in the RapidAPI dashboard (Basic / Pro / Ultra plans). See docs/RAPIDAPI-SETUP.md in the project repository for details.