Dokumentacja API - Otwarte Dane Kolejowe

📋 Spis treści

🚀 Wprowadzenie
🔐 Autoryzacja
📡 Endpoints
⚡ Limity zapytań
💡 Przykłady
❌ Obsługa błędów

🚀 Wprowadzenie

OpenData API zapewnia dostęp do otwartych danych kolejowych. API umożliwia pobieranie informacji o:

📍 Stacjach kolejowych
🚆 Rozkładach jazdy (planowych)
⏰ Bieżących danych z wykonania (real-time)
🚧 Utrudnieniach w ruchu

ℹ️ Informacja: Aby korzystać z API, potrzebujesz klucza API. Złóż wniosek o klucz na stronie głównej.

Base URL

🌐 Wersjonowanie: API używa wersjonowania w URL. Aktualna wersja to v1. Można również użyć nagłówka X-Api-Version: 1.0 lub parametru ?api-version=1.0

Format odpowiedzi

Wszystkie odpowiedzi są w formacie JSON. Standardowa struktura odpowiedzi:

{
  "success": true,
  "data": { ... },
  "timestamp": "2025-10-21T10:30:00Z"
}

🔐 Autoryzacja

API wymaga autoryzacji za pomocą klucza API. Klucz można przekazać na trzy sposoby:

1. Header X-API-Key (zalecane)

X-API-Key: sk_live_your_api_key_here

2. Authorization Bearer

Authorization: Bearer sk_live_your_api_key_here

3. Authorization ApiKey

Authorization: ApiKey sk_live_your_api_key_here

⚠️ Ważne: Nie udostępniaj swojego klucza API publicznie. Przechowuj go bezpiecznie jako zmienną środowiskową lub w konfiguracji.

📡 Główne Endpoints

🚆 Rozkłady i Wykonanie

GET /api/v1/schedules - Rozkład planowy

Zwraca rozkład planowy dla podanych stacji i przedziału dat.

Parametr	Typ	Wymagany	Opis
dateFrom	date	Nie	Data początkowa (YYYY-MM-DD). Domyślnie: dzisiaj
dateTo	date	Nie	Data końcowa (max 31 dni). Domyślnie: dzisiaj
stations	string	Nie	Lista ID stacji oddzielonych przecinkami (np. "33506,33512"). Domyślnie: wszystkie stacje
carriersInclude	string	Nie	Lista przewoźników do uwzględnienia (np. "IC,KM"). Zobacz /dictionaries/carriers
carriersExclude	string	Nie	Lista przewoźników do wykluczenia. Zobacz /dictionaries/carriers

GET /api/v1/operations - Realizacja pociągów (real-time)

Zwraca informacje o bieżących realizacjach pociągów z opóźnieniami.

Parametr	Typ	Wymagany	Opis
stations	string	Nie	Lista ID stacji oddzielonych przecinkami. Domyślnie: wszystkie stacje
carriersInclude	string	Nie	Lista przewoźników do uwzględnienia
carriersExclude	string	Nie	Lista przewoźników do wykluczenia

GET /api/v1/disruptions - Utrudnienia w ruchu

Zwraca informacje o aktualnych utrudnieniach w ruchu kolejowym.

Parametr	Typ	Wymagany	Opis
dateFrom	date	Nie	Data początkowa. Domyślnie: dzisiaj
dateTo	date	Nie	Data końcowa (max 31 dni). Domyślnie: dzisiaj
stations	string	Nie	Lista ID stacji. Domyślnie: wszystkie stacje

📚 Słowniki danych

GET /api/v1/dictionaries/carriers - Lista przewoźników

Zwraca listę wszystkich przewoźników z ich kodami (skrótami) używanymi w parametrach carriersInclude i carriersExclude.

💡 Przykładowe kody przewoźników: IC (PKP Intercity), KM (Koleje Mazowieckie), KS (Koleje Śląskie), KD (Koleje Dolnośląskie)

GET /api/v1/dictionaries/stations - Lista stacji

Zwraca listę stacji z ich ID używanymi w parametrze stations.

Parametr	Typ	Wymagany	Opis
search	string	Nie	Wyszukiwanie po nazwie stacji (max 500 wyników)

GET /api/v1/dictionaries/commercial-categories - Kategorie handlowe

Zwraca listę kategorii handlowych pociągów.

GET /api/v1/dictionaries/stop-types - Typy postoów

Zwraca listę typów postójów na stacjach.

🔍 Diagnostyka

GET /api/diagnostics/import-info - Informacje o importach

Zwraca informacje o ostatnich importach danych (rozkład i wykonanie).

GET /api/diagnostics/health - Health Check

Sprawdza status API (nie wymaga autoryzacji).

🔑 Zarządzanie kluczem API

POST /api/v1/apikey/generate - Generuj klucz API

GET /api/v1/apikey/info - Informacje o kluczu

GET /api/v1/apikey/usage - Statystyki użycia

⚡ Limity zapytań

API implementuje limity zapytań aby zapewnić stabilność usługi i chronić przed nadużyciami. Limity są przyznawane na podstawie wybranego poziomu podczas składania wniosku o klucz API:

Poziom dostępu	Limit godzinowy	Limit dzienny	Przeznaczenie
Basic	100	1 000	Deweloperzy, testy, małe projekty hobbystyczne
Standard	500	5 000	Małe i średnie aplikacje mobilne
Premium	2 000	20 000	Tablice informacyjne, większe integracje

📊 Przykłady użycia:

Basic (~1-2 req/min) - sprawdzanie opóźnień dla 1-2 stacji co kilka minut
Standard (~8 req/min) - aplikacja mobilna odświeżająca dane dla kilku użytkowników
Premium (~33 req/min) - tablica informacyjna odświeżająca co 2-3 sekundy

💡 Wskazówka: Monitoruj nagłówki odpowiedzi aby śledzić pozostałe limity:
X-RateLimit-Hourly-Remaining - pozostałe zapytania w tej godzinie
X-RateLimit-Daily-Remaining - pozostałe zapytania dzisiaj

⚠️ Uwaga: Po przekroczeniu limitu otrzymasz odpowiedź z kodem HTTP 429 (Too Many Requests). Poczekaj do resetu limitu lub rozważ upgrade do wyższego poziomu.

💡 Przykłady użycia

📅 Pobieranie rozkładu planowego

Wszystkie parametry są opcjonalne. Bez parametrów zwraca rozkład na dzisiaj dla wszystkich stacji:

# Bez parametrów - rozkład na dziś dla wszystkich stacji
curl -H "X-API-Key: your_api_key_here" \
  "/api/v1/schedules"

# Z parametrami - rozkład na wybrane daty i stacje
curl -H "X-API-Key: your_api_key_here" \
  "/api/v1/schedules?dateFrom=2025-10-21&dateTo=2025-10-22&stations=33506"

⏰ Sprawdzanie realizacji pociągów (real-time)

Bez parametru stations zwraca dane dla wszystkich stacji:

# Bez parametrów - wszystkie stacje
curl -H "X-API-Key: your_api_key_here" \
  "/api/v1/operations"

# Dla wybranych stacji
curl -H "X-API-Key: your_api_key_here" \
  "/api/v1/operations?stations=33506,33512"

🚧 Pobieranie utrudnień

Bez parametrów zwraca utrudnienia na dzisiaj dla wszystkich stacji:

# Bez parametrów - utrudnienia na dziś
curl -H "X-API-Key: your_api_key_here" \
  "/api/v1/disruptions"

# Z parametrami - utrudnienia w wybranym zakresie dat
curl -H "X-API-Key: your_api_key_here" \
  "/api/v1/disruptions?dateFrom=2025-10-21&dateTo=2025-10-31"

🌐 JavaScript/Fetch

const response = await fetch('/api/v1/operations?stations=33506', {
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

🐍 Python/Requests

import requests

headers = {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
}

response = requests.get(
    '/api/v1/schedules',
    headers=headers,
    params={
        'dateFrom': '2025-10-21',
        'dateTo': '2025-10-22',
        'stations': '33506'
    }
)
data = response.json()
print(data)

❌ Obsługa błędów

API zwraca standardowe kody błędów HTTP wraz z opisem w JSON:

Kod HTTP	Znaczenie	Przykład
400	Bad Request	Nieprawidłowe parametry zapytania
401	Unauthorized	Brak lub nieprawidłowy klucz API
403	Forbidden	Brak uprawnień do zasobu
404	Not Found	Zasób nie został znaleziony
429	Too Many Requests	Przekroczono limit zapytań
500	Internal Server Error	Błąd serwera

Przykład odpowiedzi błędu:

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid API key provided",
  "timestamp": "2025-10-21T10:30:00Z",
  "details": {
    "code": "INVALID_API_KEY",
    "hint": "Check if your API key is active and correctly formatted"
  }
}

⚠️ Wskazówki dotyczące obsługi błędów:

Implementuj retry logic dla błędów 5xx
Respektuj limity zapytań (429)
Waliduj dane przed wysłaniem (400)
Przechowuj klucz API bezpiecznie (401)

📞 Kontakt i wsparcie

W przypadku pytań lub problemów z API:

📧 Email: pdp-api@plk-sa.pl
📋 Interaktywna dokumentacja: Swagger UI | Scalar
🔑 Klucz API: Wniosek na stronie głównej

📈 Feedback: Twoje opinie pomagają nam ulepszać API. Podziel się swoimi doświadczeniami!