📬 PNA (Postal Codes) API Documentation

[EN] High-performance API for searching Polish Postal Codes (PNA), validating addresses, and autocomplete suggestions. Optimized for precise house number matching (ranges, odd/even logic). [PL] Wysokowydajne API do wyszukiwania kodów pocztowych (PNA), weryfikacji adresów i autouzupełniania. Zoptymalizowane pod kątem precyzyjnego dopasowania numerów domów (zakresy, parzystość).

PL Jeśli jesteś zainteresowany(a) użyciem API, skontaktuj się proszę przez formularz kontaktowy: https://wroclawprogramowanie/contact-form/

EN If you’re interested in using the API, please contact us via the contact form: https://wroclawprogramowanie/contact-form/

🔐 Authentication / Uwierzytelnianie

[EN] All requests require an API Key (Header) or Bearer Token. [PL] Wszystkie zapytania wymagają klucza API (Nagłówek) lub tokena Bearer.

🚀 Endpoints / Punkty Końcowe

1. Search Postal Code (GET) / Szukaj Kodu (GET)

[EN] Find PNA based on address details. Supports house numbers. [PL] Znajdź PNA na podstawie adresu. Obsługuje numery domów.

Endpoint: GET /pna/search

Parameters:

• city (required): City name (e.g., “Wrocław”)
• street (optional): Street name (e.g., “Kwiska”)
• number (optional): House number (e.g., “31”, “2a”)

Example / Przykład:

bashcurl -X GET "https://pnaapi.wroclawprogramowanie.pl/pna/search?city=Wrocław&street=Kwiska&number=3" \
     -H "Authorization: Bearer <token>"

Response / Odpowiedź:

json[
  {
    "postal_code": "54-210",
    "city": "Wrocław",
    "street": "Kwiska",
    "district": "Wrocław-Fabryczna",
    "ranges": [
      { "from": "1", "to": "11a", "parity": "ODD" }
    ]
  }
]

2. Search Postal Code (POST) / Szukaj Kodu (POST)

[EN] Advanced search using JSON body. Recommended for complex queries. [PL] Zaawansowane wyszukiwanie przy użyciu JSON. Zalecane dla złożonych zapytań.

Endpoint: POST /pna/search

Body:

json{
  "city": "Białystok",
  "street": "Mikołaja Kopernika",
  "number": "2a",
  "province": "podlaskie"
}

Example / Przykład:

bashcurl -X POST "https://pnaapi.wroclawprogramowanie.pl/pna/search" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>" \
     -d '{"city": "Białystok", "street": "Mikołaja Kopernika", "number": "2a"}'

3. Get Addresses by Code (GET) / Adresy dla Kodu (GET)

[EN] Retrieve all streets assigned to a specific Postal Code. [PL] Pobierz wszystkie ulice przypisane do danego kodu pocztowego.

Endpoint: GET /pna/code/{postalCode}

Example / Przykład:

bashcurl -X GET "https://pnaapi.wroclawprogramowanie.pl/pna/code/54-210" \
     -H "Authorization: Bearer <token>"

4. Get Addresses by Code (POST) / Adresy dla Kodu (POST)

[EN] Retrieve addresses for a Postal Code sent in JSON body. [PL] Pobierz adresy dla kodu przesłanego w ciele JSON.

Endpoint: POST /pna/code

Body:

json{
  "postal_code": "54-210"
}

Example / Przykład:

bashcurl -X POST "https://pnaapi.wroclawprogramowanie.pl/pna/code" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>" \
     -d '{"postal_code": "54-210"}'

5. Reverse Geocoding

[EN] Finds nearest Postal Codes for given coordinates. [PL] Znajduje najbliższe kody pocztowe dla zadanych współrzędnych.

Endpoint: GET /pna/reverse Parameters:

• Lat (required): Latitude between -90 and 90
• Lon (required): Longitude between -180 and 180
• RadiusKm (optional): Radius between 0.1 and 50 km (default 5)

Endpoint: POST /pna/reverse

Body:

json{
  "lat": 51.12161528781476,
  "lon": 16.98550601056978,
  "radius_km": 0.1
}

Example / Przykład:

curl -X 'POST' \
  'https://pnaapi.wroclawprogramowanie.pl/pna/reverse' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "lat": 51.12161528781476,
  "lon": 16.98550601056978,
  "radius_km": 0.1
}'

6. Autocomplete Streets / Podpowiedzi Ulic

[EN] Get real-time street suggestions. [PL] Pobierz podpowiedzi nazw ulic w czasie rzeczywistym.

Endpoint: GET /pna/autocomplete/streets

Parameters:

• query (min 2 chars): Partial street name / Fragment nazwy
• city (optional): Filter by city / Filtruj po mieście

Example / Przykład:

bashcurl -X GET "https://api.example.com/pna/autocomplete/streets?query=Legn&city=Wrocław" \
     -H "Authorization: Bearer <token>"

Response / Odpowiedź:

json
["Legnicka", "Legnicka Mała"]

7. Autocomplete Cities / Podpowiedzi Miast

[EN] Get real-time city suggestions. [PL] Pobierz podpowiedzi nazw miast w czasie rzeczywistym.

Endpoint: GET /pna/autocomplete/cities

Example / Przykład:

bashcurl -X GET "https://pnaapi.wroclawprogramowanie.pl/pna/autocomplete/cities?query=Wroc" \
     -H "Authorization: Bearer <token>"

🤖 AI Integration / Integracja z AI

[EN] This API is AI-Ready. Use the following endpoints for LLM context: [PL] To API jest gotowe na AI. Użyj poniższych endpointów dla kontekstu LLM:

• GET /pna/ai-guide - Semantic instructions / Instrukcje semantyczne
• GET /.well-known/ai-plugin.json - OpenAI Plugin Manifest / Manifest Pluginu OpenAI