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. Endpointy zwracają bezpośrednio obiekt DTO (bez owijki {success, data, ...}). Przykład odpowiedzi z /api/v1/dictionaries/carriers:

{
  "generatedAt": "2026-04-28T10:30:00Z",
  "carriers": [
    { "code": "IC", "name": "PKP Intercity S.A.", "validFrom": null, "validTo": null }
  ],
  "usage": { "description": "...", "examples": ["..."] }
}

Każdy endpoint ma swój własny schemat odpowiedzi opisany w specyfikacji OpenAPI.

🔐 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
fullRoutes	bool	Nie	Jeśli true, zwraca pełne trasy pociągów (domyślnie: false)
withPlanned	bool	Nie	Jeśli true, dołącza planowe czasy i obliczone opóźnienia w minutach (domyślnie: false)
page	int	Nie	Numer strony (domyślnie: 1)
pageSize	int	Nie	Liczba rekordów na stronę (domyślnie: 1000, max: 10000)

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
carriersInclude	string	Nie	Lista przewoźników do uwzględnienia
carriersExclude	string	Nie	Lista przewoźników do wykluczenia

📚 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
page	int	Nie	Numer strony (domyślnie: 1)
pageSize	int	Nie	Liczba wyników na stronę (domyślnie: 500, max: 5000)

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 postojów na stacjach.

📎 Dodatkowe endpointy

💡 Wersje ze skróconymi nazwami pól (shortened): Każdy główny endpoint danych posiada wariant /shortened zwracający te same dane, ale ze skróconymi nazwami pól JSON (np. scheduleId → sid). Zmniejsza to rozmiar odpowiedzi.

GET /api/v1/schedules/shortened
GET /api/v1/operations/shortened
GET /api/v1/disruptions/shortened

GET /api/v1/schedules/route/{scheduleId}/{orderId} - Trasa konkretnego pociągu (rozkład)

Zwraca szczegółową trasę pociągu z rozkładu planowego. Dostępna również wersja /shortened.

GET /api/v1/schedules/routes/{date} - Lista identyfikatorów tras na daną datę

Zwraca listę identyfikatorów tras (scheduleId/orderId) kursujących w podanym dniu. Dostępna również wersja /shortened.

GET /api/v1/operations/train/{scheduleId}/{orderId}/{operatingDate} - Trasa konkretnego pociągu (wykonanie)

Zwraca dane o wykonaniu konkretnego pociągu (np. /api/v1/operations/train/2026/607309466/2026-02-16).

GET /api/v1/operations/statistics - Statystyki statusów pociągów

Zwraca statystyki pociągów (w trasie, zakończone, odwołane itp.).

Parametr	Typ	Wymagany	Opis
date	date	Nie	Data statystyk (YYYY-MM-DD). Domyślnie: dzisiaj

GET /api/v1/data-version - Wersja danych

Zwraca aktualne wersje (GUID) danych rozkładu i wykonania. Pozwala sprawdzić czy dane się zmieniły od ostatniego pobrania.

📋 Słowniki pól

Endpointy opisujące strukturę pól w odpowiedziach JSON (nie wymagają autoryzacji):

GET/api/v1/fields/schedules

GET/api/v1/fields/schedules/csv

GET/api/v1/fields/operations

GET/api/v1/fields/operations/csv

GET/api/v1/fields/disruptions

GET/api/v1/fields/disruptions/csv

🔑 Zarządzanie kluczem API

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

POST/api/v1/apikey/accept-terms - akceptacja regulaminu

GET/api/v1/apikey/verify-email - weryfikacja e-mail (link)

POST/api/v1/apikey/verify-email - weryfikacja e-mail (kod)

POST/api/v1/apikey/resend-verification - ponowne wysłanie kodu

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

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

PUT/api/v1/apikey/update - edycja danych klucza

POST/api/v1/apikey/deactivate - dezaktywacja klucza

📜 Polityka prywatności i regulamin

GET/api/v1/privacy - treść polityki (Markdown)

GET/api/v1/privacy/html - treść polityki (HTML)

GET/api/v1/terms - treść regulaminu (Markdown)

GET/api/v1/terms/html - treść regulaminu (HTML)

GET/api/v1/terms/version - aktualna wersja regulaminu

GET/api/version - wersja aplikacji

⚡ 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 (schemat `ApiError`):

{
  "error": "Unauthorized",
  "message": "Invalid API key provided",
  "details": null,
  "timestamp": "2026-04-28T10:30:00Z",
  "path": "/api/v1/schedules",
  "traceId": "00-9c3a9fbd...-01"
}

Pole traceId jest identyfikatorem żądania w logach serwera — przy zgłaszaniu problemu wsparciu warto go podać. Pole path zawiera ścieżkę żądania wraz z query string.

⚠️ 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)

🗂️ Wersjonowanie i changelog

API używa wersjonowania w segmencie URL (/api/v1/...). Wersję można też przekazać nagłówkiem X-Api-Version: 1.0 lub parametrem ?api-version=1.0.

Polityka kompatybilności

Zmiany niełamiące (dodanie nowego pola, nowego endpointu, nowej wartości enum, nowego parametru opcjonalnego) — wprowadzane w obrębie wersji v1 bez ogłoszenia.
Zmiany łamiące (usunięcie pola, zmiana typu pola, zmiana semantyki) — wprowadzane przez nową wersję główną (v2) z minimum 90-dniowym okresem przejściowym, w którym obie wersje działają równolegle.
Pola oznaczone [DEPRECATED] w opisie OpenAPI mogą zostać usunięte w kolejnej wersji głównej. Przykład: plannedArrivalTime, plannedDepartureTime (TimeSpan) — wycofywane w v2.0 na rzecz plannedArrival/plannedDeparture (DateTime).
Każda zmiana wprowadzona w API jest opisana w changelogu.

Komunikacja zmian

Changelog publikowany pod adresem /changelog.md zawiera kompletną historię zmian z datami.
O zmianach łamiących integratorzy są informowani e-mailem na adres podany przy wniosku o klucz API, z minimum 30-dniowym wyprzedzeniem przed wdrożeniem.
Endpoint /api/v1/data-version zwraca aktualną wersję danych (GUID) — pozwala wykryć, czy dane się zmieniły od ostatniego pobrania.
Endpoint /api/version zwraca wersję wdrożonej aplikacji.

📞 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!