Kody Pocztowe Poczty Polskiej API

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' 'https://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'

Pobranie kodu pocztowego dla adresu z numerem domu:


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

W miejsce MIASTO wpisz nazwę miasta, w miejsce ULICA nazwę ulicy, a w miejsce NUMER numer domu (np. 12b).
Wielkość liter nie ma znaczenia, a przedrostki ul., al., pl., os. można pominąć; wystarczy też końcówka nazwy (np. Piłsudskiego).
Opcjonalny parametr district zawęża wynik do dzielnicy, np. ?district=Żoliborz.
W odpowiedzi zwrócone zostaną informacje o kodach (opis pól), których numeracja obejmuje podany numer. Ulica bez opisu numeracji obejmuje każdy numer.

Przykład:


                    curl -H 'Accept:application/json' 'https://kodpocztowy.intami.pl/city/Szczecin/street/Piłsudskiego/number/40'

Walidacja adresu i kodu pocztowego:


                    curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"kod":"KOD","miejscowosc":"MIASTO","ulica":"ULICA","numer":"NUMER","dzielnica":"DZIELNICA"}' 'https://kodpocztowy.intami.pl/validate'

Sprawdza, czy kod pocztowy pasuje do miejscowości, ulicy i numeru domu. Wymagane jest tylko pole miejscowosc; bez pola kod odpowiedź podaje właściwy kod adresu. Dla miejscowości bez ulic sprawdzana jest sama miejscowość.
Odpowiedź (application/json lub application/xml) zawiera pola: poprawny (czy kod pasuje do adresu), kody (właściwe kody), dopasowania (pasujące wpisy, opis pól) i uwagi, np. kod 70-420 nie pasuje do numeru 40; właściwy 70-421, nie ma ulicy Długa w miejscowości Szczecin.
Jedno wywołanie to jedno zapytanie z limitu.

Przykład:


                    curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"kod":"70-420","miejscowosc":"Szczecin","ulica":"al. Piłsudskiego","numer":"40"}' 'https://kodpocztowy.intami.pl/validate'

Opis pól:

nazwa pola	opis	wymagalność
`kod`	kod pocztowy w formacie xx-xxx	zawsze
`nazwa`	nazwa jednostki	występuje dla jednostek, którym przydzielono indywidualny kod pocztowy
`miejscowosc`	nazwa miejscowości	opcjonalnie (pole jest pomijane, gdy jest puste)
`ulica`	ulica	opcjonalnie
`numer`	numer budynku	występuje dla jednostek, którym przydzielono indywidualny kod pocztowy
`gmina`	gmina	opcjonalnie (pole jest pomijane, gdy jest puste)
`powiat`	powiat	zawsze
`wojewodztwo`	województwo	zawsze
`dzielnica`	dzielnica miasta	opcjonalnie
`numeracja`	lista zasad numeracji (w XML elementy `zasada`); pusta lista oznacza, że kod obejmuje każdy numer	zawsze
`numeracja[].od`	początek zakresu numeracji	zawsze
`numeracja[].do`	koniec zakresu numeracji; pusty oznacza „do końca”	zawsze (w XML pomijane, gdy puste)
`numeracja[].parzystosc`	`PARZYSTE` lub `NIEPARZYSTE`	opcjonalnie; bez niego zakres obejmuje wszystkie numery

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, tak samo jak wywołanie zakończone błędem (np. błędne argumenty); wyszukiwanie bez wyniku limit pobiera. 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. Do limitu (także do pakietu zapytań) liczą się odpowiedzi z wynikiem oraz zapytania, które niczego nie znalazły (404). Zapytanie z błędnym parametrem (400) albo zakończone błędem serwera (5xx) niczego nie zużywa.

Niezależnie od limitu dobowego obowiązuje limit techniczny: 120 zapytań na minutę z jednego adresu IP (także z kluczem API). Po jego przekroczeniu usługa odpowie kodem http 429 - "Too Many Requests" z nagłówkiem Retry-After: 60 (sekundy do ponowienia zapytania).

Jeśli Twoja aplikacja potrzebuje zwiększonego limitu możesz skorzystać z jednego z płatnych planów dostępnych za pośrednictwem .
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.

Kody Pocztowe API

Opis

Wspierane formaty odpowiedzi:

Użycie:

Pobranie informacji o kodzie pocztowym:

Przykład:

Pobranie kodów pocztowych przypisanych do miasta:

Przykład:

Pobranie kodów pocztowych przypisanych do dzielnicy miasta:

Przykład:

Pobranie kodów pocztowych przypisanych do ulicy w mieście:

Przykład:

Pobranie kodu pocztowego dla adresu z numerem domu:

Przykład:

Walidacja adresu i kodu pocztowego:

Przykład:

Opis pól:

MCP — Model Context Protocol

Adres usługi MCP:

Dostępne narzędzia (tools):

Konfiguracja klienta MCP:

Limity:

Ograniczenia:

Kontakt

Demo

Explore the API

Sprawdź też inne API

QRCode and BarCode decoder/generator

Geo Data API