Kody Pocztowe API

Darmowe API pozwalające pobrać adres przy użyciu kodu pocztowego Poczty Polskiej.

Opis

Wspierane formaty odpowiedzi:

  • application/json - format JSON (domyślny format)
  • application/xml - format XML
  • text/plain - format tekstowy

Użycie:

Pobranie informacji o kodzie pocztowym:

curl -H 'Accept:application/json' 'https://kodpocztowy.intami.pl/api/KOD'

W miejsce KOD wpisz kod pocztowy w formacie xx-xxx.
Ustaw nagłówek Accept na wybrany format odpowiedzi.
W odpowiedzi zwrócone zostaną informacje opisane w opis pól w wybranym formacie.

Przykład:
curl -H 'Accept:application/json' 'https://kodpocztowy.intami.pl/api/01-111'

Pobranie kodów pocztowych przypisanych do miasta:

curl -H 'Accept:application/json' 'https://kodpocztowy.intami.pl/city/MIASTO'

W miejsce MIASTO wpisz nazwę miasta.
Ustaw nagłówek Accept na wybrany format odpowiedzi.
W odpowiedzi zwrócona zostanie lista kodów pocztowych przypisanych do miasta.
Uwaga: Jeśli istnieje więcej niż jedno miasto o tej nazwie to zostaną zwrócne kody ze wszystkich miast.

Przykład:
curl -H 'Accept:application/json' 'http://kodpocztowy.intami.pl/city/Wrocław'

Pobranie kodów pocztowych przypisanych do dzielnicy miasta:

curl -H 'Accept:application/json' 'https://kodpocztowy.intami.pl/city/MIASTO/district/DZIELNICA'

W miejsce MIASTO wpisz nazwę miasta, a w miejsce DZIELNICA nazwę dzielnicy.
Ustaw nagłówek Accept na wybrany format odpowiedzi.
W odpowiedzi zwrócona zostanie lista kodów pocztowych przypisanych do dzielnicy miasta.

Przykład:
curl -H 'Accept:application/json' 'https://kodpocztowy.intami.pl/city/Wrocław/district/Oporów'
Pobranie kodów pocztowych przypisanych do ulicy w mieście:
curl -H 'Accept:application/json' 'https://kodpocztowy.intami.pl/city/MIASTO/street/ULICA'

W miejsce MIASTO wpisz nazwę miasta, a w miejsce ULICA nazwę ulicy.
Ustaw nagłówek Accept na wybrany format odpowiedzi.
W odpowiedzi zwrócona zostanie lista kodów pocztowych przypisanych do ulicy w tym miescie.

Przykład:
curl -H 'Accept:application/json' 'https://kodpocztowy.intami.pl/city/Wrocław/street/Grodzka'

Opis pól:

nazwa polaopiswymagalność
Kodkod pocztowy w formacie xxx-xxxzawsze
Nazwanazwa jednostkiwystępuje dla jednostek, którym przydzielono indywidualny kod pocztowy
Miejscowośćnazwa miejscowościzawsze
Ulicaulicaopcjonalnie
Numernumer budynkuwystępuje dla jednostek, którym przydzielono indywidualny kod pocztowy
Numeracjaopis numeracjiopcjonalnie
Gminagminazawsze
Powiatpowiatzawsze
Dzielnicadzielnica miastaopcjonalnie

MCP — Model Context Protocol

API udostępnia także endpoint MCP (Model Context Protocol), dzięki czemu modele językowe / LLMy mogą samodzielnie wyszukiwać informacje o polskich kodach pocztowych.

Adres usługi MCP:

https://kodpocztowy.intami.pl/mcp

Endpoint używa transportu streamable HTTP i nie wymaga uwierzytelnienia.

Dostępne narzędzia (tools):

Aktualny opis serwera i jego narzędzi wraz z parametrami: kodpocztowy.intami.pl/mcp.

Konfiguracja klienta MCP:

{
  "mcpServers": {
    "kody-pocztowe": {
      "type": "http",
      "url": "https://kodpocztowy.intami.pl/mcp"
    }
  }
}

Limity:

Endpoint MCP podlega tym samym limitom co reszta API: 50 zapytań na dobę z jednego adresu IP dla planu darmowego. Wywołania narzędzi pobierają limit, inicjalizacja i lista narzędzi - nie. Po przekroczeniu limitu narzędzie zwraca błąd z informacją o płatnych planach. Agent może kupić pakiet zapytań narzędziem buy_package i przekazywać otrzymany klucz w argumencie api_key narzędzi.

Ograniczenia:

Ilość zapytań z jednego adresu IP jest ograniczona do 50 zapytań na dobę. W przypadku przekroczenia tego limitu usługa odpowie kodem http 402 - "Payment Required" wraz z informacją o płatnych planach.

Jeśli Twoja aplikacja potrzebuje zwiększonego limitu możesz skorzystać z jednego z płatnych planów dostępnych za pośrednictwem RapidAPI Polish Zip Codes .
Sprawdź dostępne plany subskrypcji.

Dla agentów AI: pakiety zapytań bez limitu dobowego i bez terminu ważności, kupowane płatnością x402 w USDC (pakiet pro: 30 000 zapytań za 5 USD, mega: 900 000 zapytań za 12 USD). Aktualne pakiety i sieć: GET /x402/packages, zakup: POST /x402/packages/{id}. W odpowiedzi otrzymasz klucz API, który należy wysyłać w nagłówku X-API-Key; zakup z tym nagłówkiem doładowuje ten sam klucz. Liczbę pozostałych zapytań pakietu zwraca nagłówek X-Requests-Remaining każdej odpowiedzi.

Kontakt

Jeśli uważasz, że brakuje jakieś funkcjonalości lub potrzebujesz pomocy napisz email.

Demo

Explore the API

Sprawdź też inne API

QRCode and BarCode decoder/generator

Extract and decode QRCodes and BarCodes from a document. Generate QRCodes and BarCodes.

Geo Data API

Provides basic geographical data. Resolves location by IP.