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://polish-address-postal-code-api.p.rapidapi.com/v1/autocomplete/unified?q=wroc&limit=10' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: polish-address-postal-code-api.p.rapidapi.com'

Postal code — full assignment list

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

City postal codes

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

Postal codes — district

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

Postal codes — street in city

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

Full address (TERYT sym + optional symUl)

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

Region hierarchy — provinces

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

MCP — Model Context Protocol

The API is also exposed as an MCP server, so language models and AI assistants can look up Polish addresses and postal codes on their own. Each REST endpoint maps to one MCP tool with a short operationId name.

MCP gateway: https://mcp.rapidapi.com with header x-api-host: polish-address-postal-code-api.p.rapidapi.com. Clients connect via streamable HTTP (mcp-remote). Authentication uses your RapidAPI subscription key (x-api-key header).

Available tools

Tool Description
autocomplete_unified Unified autocomplete (localities + streets)
autocomplete_localities Autocomplete localities
autocomplete_streets Autocomplete streets
autocomplete_postal Autocomplete postal codes
lookup_by_zip Lookup by postal code
lookup_by_city Postal codes for a city
lookup_by_city_district Postal codes for a city district
lookup_by_city_street Postal codes for a street in a city
resolve_address Resolve address by SIMC sym and optional SYM_UL
resolve_by_path Resolve by TERYT label path
list_provinces List provinces
list_counties Counties in province
list_communes Communes in county
list_localities Localities in commune
list_districts Districts (dzielnice) for locality
list_streets Streets in locality

Client configuration (Cursor)

Copy the snippet from RapidAPI Playground → MCP, or use the example below. Replace YOUR_RAPIDAPI_KEY with your key from the dashboard. Use a short server name (e.g. pl-addresses) to stay within client name limits. 

{
  "mcpServers": {
    "pl-addresses": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.rapidapi.com",
        "--header",
        "x-api-host: polish-address-postal-code-api.p.rapidapi.com",
        "--header",
        "x-api-key: YOUR_RAPIDAPI_KEY"
      ]
    }
  }
}

See also RapidAPI: Consume APIs using AI.

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.