📚 Dokumentacja API

Pełna dokumentacja REST API dla polskich kodów pocztowych

Spis treści

1. Wprowadzenie

API Kodów Pocztowych to prosty i szybki sposób na dostęp do bazy polskich kodów pocztowych. API zwraca odpowiedzi w formacie JSON i obsługuje wyszukiwanie według różnych kryteriów.

📌 Ważne: Wszystkie żądania wymagają klucza API. Klucz możesz uzyskać po zakupie dostępu w panelu użytkownika.

Podstawowe informacje

2. Autentykacja

Każde zapytanie do API wymaga podania klucza API. Klucz możesz przekazać na dwa sposoby:

Sposób 1: Nagłówek HTTP (zalecany)

HTTP
Authorization: Bearer twoj_klucz_api

Sposób 2: Parametr URL

URL
https://kodypocztowe.ict-systems.pl/api/v1/search?code=47-120&api_key=twoj_klucz_api
⚠️ Uwaga: Zalecamy używanie nagłówka HTTP zamiast parametru URL ze względów bezpieczeństwa.

3. Endpointy

3.2. Statystyki użycia

GET /api/v1/stats

Endpoint zwracający statystyki wykorzystania Twojego klucza API.

✅ Darmowe zapytanie: Ten endpoint nie jest liczony do limitu zapytań. Możesz sprawdzać swoje statystyki bez obaw o przekroczenie limitu.

Parametry zapytania

Ten endpoint nie wymaga żadnych parametrów (poza kluczem API).

Struktura odpowiedzi

JSON
{ "success": true, "data": { "email": "user@example.com", "api_key": "0a75c752...b458207f", "requests_limit": 10000, "requests_used": 1523, "requests_remaining": 8477, "expires_at": "2026-01-20 12:34:56", "is_active": true, "created_at": "2025-12-20 10:15:30" } }

4. Parametry wyszukiwania - szczegóły

Wyszukiwanie po kodzie pocztowym (code)

Wyszukuje dokładne dopasowanie kodu pocztowego.

Przykład:
?code=47-120

Zwróci wszystkie adresy z kodem pocztowym 47-120

Wyszukiwanie po mieście (city)

Wyszukuje miejscowości zawierające podany ciąg znaków (wielkość liter nie ma znaczenia).

Przykłady:
?city=Warszawa
?city=warsz - znajdzie Warszawa, Warszowice, itp.
?city=gorzyce - znajdzie Gorzyce, Gorzyczki, itp.

Wyszukiwanie po ulicy (street)

Wyszukuje ulice zawierające podany ciąg znaków.

Przykłady:
?street=Marszałkowska
?street=Główna
?street=aleja&city=Katowice - łączone z miastem

Wyszukiwanie po województwie (voivodeship)

Wyszukuje adresy w danym województwie.

Dostępne województwa:
  • dolnośląskie
  • kujawsko-pomorskie
  • lubelskie
  • lubuskie
  • łódzkie
  • małopolskie
  • mazowieckie
  • opolskie
  • podkarpackie
  • podlaskie
  • pomorskie
  • śląskie
  • świętokrzyskie
  • warmińsko-mazurskie
  • wielkopolskie
  • zachodniopomorskie

Limit wyników (limit)

Ogranicza liczbę zwracanych wyników (1-100, domyślnie 20).

Przykład:
?city=Warszawa&limit=50

Zwróci maksymalnie 50 wyników dla Warszawy

5. Przykłady użycia

Przykład 1: Wyszukiwanie po kodzie pocztowym

cURL
curl -X GET "https://kodypocztowe.ict-systems.pl/api/v1/search?code=47-120" \ -H "Authorization: Bearer twoj_klucz_api"
// Odpowiedź { "success": true, "data": [ { "id": 45821, "code": "47-120", "city": "Brynek", "street": "", "commune": "Gorzyce", "county": "wodzisławski", "voivodeship": "śląskie", "numbers": "" } ], "count": 1, "limit": 20 }

Przykład 2: Wyszukiwanie po mieście

cURL
curl -X GET "https://kodypocztowe.ict-systems.pl/api/v1/search?city=Gorzyce&limit=5" \ -H "Authorization: Bearer twoj_klucz_api"
// Zwróci maksymalnie 5 wyników dla miejscowości zawierających "Gorzyce" { "success": true, "data": [...], "count": 5, "limit": 5 }

Przykład 3: Łączone wyszukiwanie (miasto + ulica)

cURL
curl -X GET "https://kodypocztowe.ict-systems.pl/api/v1/search?city=Warszawa&street=Marszałkowska" \ -H "Authorization: Bearer twoj_klucz_api"
// Zwróci adresy na ul. Marszałkowskiej w Warszawie { "success": true, "data": [...], "count": 3, "limit": 20 }

Przykład 4: Wyszukiwanie po województwie

cURL
curl -X GET "https://kodypocztowe.ict-systems.pl/api/v1/search?voivodeship=śląskie&limit=10" \ -H "Authorization: Bearer twoj_klucz_api"
// Zwróci 10 wyników z województwa śląskiego { "success": true, "data": [...], "count": 10, "limit": 10 }

Przykład 5: Sprawdzanie statystyk

cURL
curl -X GET "https://kodypocztowe.ict-systems.pl/api/v1/stats" \ -H "Authorization: Bearer twoj_klucz_api"
{ "success": true, "data": { "email": "user@example.com", "api_key": "0a75c752...b458207f", "requests_limit": 10000, "requests_used": 1523, "requests_remaining": 8477, "expires_at": "2026-01-20 12:34:56", "is_active": true, "created_at": "2025-12-20 10:15:30" } }

Przykład 6: Użycie w JavaScript (Fetch API)

JavaScript
const apiKey = 'twoj_klucz_api'; const code = '47-120'; fetch(`https://kodypocztowe.ict-systems.pl/api/v1/search?code=${code}`, { headers: { 'Authorization: Bearer': apiKey } }) .then(response => response.json()) .then(data => { if (data.success) { console.log('Znaleziono wyników:', data.count); console.log('Dane:', data.data); } }) .catch(error => console.error('Błąd:', error));

Przykład 7: Użycie w PHP

PHP
<?php $apiKey = 'twoj_klucz_api'; $code = '47-120'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://kodypocztowe.ict-systems.pl/api/v1/search?code=$code"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "Authorization: Bearer $apiKey" ]); $response = curl_exec($ch); curl_close($ch); $data = json_decode($response, true); if ($data['success']) { echo "Znaleziono wyników: " . $data['count']; print_r($data['data']); } ?>

Przykład 8: Użycie w Python

Python
import requests api_key = 'twoj_klucz_api' code = '47-120' headers = { 'Authorization: Bearer': api_key } response = requests.get( f'https://kodypocztowe.ict-systems.pl/api/v1/search?code={code}', headers=headers ) data = response.json() if data['success']: print(f"Znaleziono wyników: {data['count']}") print(data['data'])

6. Kody błędów

Kod HTTP Znaczenie Przykładowa odpowiedź
200 OK - Zapytanie wykonane pomyślnie {"success": true, "data": [...]}
400 Bad Request - Brak parametrów wyszukiwania {"success": false, "error": "Brak parametrów wyszukiwania..."}
401 Unauthorized - Brak lub nieprawidłowy klucz API {"success": false, "error": "Nieprawidłowy klucz API"}
404 Not Found - Nieznany endpoint {"success": false, "error": "Nieznany endpoint..."}
405 Method Not Allowed - Nieprawidłowa metoda HTTP {"success": false, "error": "Metoda nie dozwolona"}
500 Internal Server Error - Błąd serwera {"success": false, "error": "Błąd serwera..."}

Przykłady błędów

Błąd: Brak klucza API

JSON
{ "success": false, "error": "Brak autoryzacji. Dodaj nagłówek Authorization: Bearer <API_KEY> lub parametr api_key." }

Błąd: Nieprawidłowy klucz API

JSON
{ "success": false, "error": "Nieprawidłowy, nieaktywny lub wygasły klucz API." }

Błąd: Brak parametrów wyszukiwania

JSON
{ "success": false, "error": "Brak parametrów wyszukiwania. Dostępne: code, city, street, voivodeship" }

7. Limity i ograniczenia

⚠️ Ważne limity:
  • Maksymalna liczba wyników na zapytanie: 100
  • Domyślna liczba wyników: 20
  • Limit zapytań zależy od wykupionego pakietu (sprawdź endpoint /stats)

Pakiety dostępu

Pakiet Limit zapytań Ważność Cena
Starter 1,000 zapytań 30 dni 49.00 PLN
Professional 10,000 zapytań 30 dni 59.00 PLN
Enterprise 100,000 zapytań 30 dni 69.00 PLN
💡 Wybierz model płatności:
  • Subskrypcja miesięczna - automatyczne odnowienie co miesiąc, możliwość anulowania w każdej chwili
  • Płatność jednorazowa - brak automatycznych płatności, dostęp na 30 dni

Cena jest taka sama niezależnie od wybranego modelu płatności.

Dobre praktyki

✅ Gotowy do testów?
Wypróbuj API używając przykładów cURL powyżej lub dowolnego narzędzia HTTP (Postman, Insomnia, itp.).