Dokumentacja API

Otwarty dostęp do historycznej bazy danych opóźnień pociągów PKP Intercity w Polsce. Buduj na danych, które do tej pory nie były łatwo dostępne.

Główny adres API (Base URL)

Wszystkie żądania wykonuj do poniższego adresu:

https://api.spoznienia.me

O projekcie

Powiadomienia o opóźnieniach na żywo są przydatne w trakcie podróży, ale brakowało ogólnodostępnej, historycznej bazy danych umożliwiającej analizy, tworzenie statystyk czy aplikacji analitycznych. Oficialne serwisy nie oferują przyjaznego API.

Spoznienia.me rozwiązuje ten problem. Codziennie automatyczny proces pobiera pełne informacje o trasach pociągów i ich realnym czasie przyjazdu/odjazdu (oraz powodach opóźnień), archiwizując je w bazie danych.

Znane ograniczenia bazy danych

Początek archiwum Baza gromadzi dane od 23 października 2025 r.
Cykl aktualizacji (t+1) Aplikacja przetwarza opóźnienia pod koniec dnia. Rzeczywiste dane z danego dnia pojawiają się w API dopiero w dniu następnym.
Stacje początkowe Dla kursów do 23 marca 2026 r. algorytm nie rejestrował poprawnie opóźnień dla niektórych pierwszych stacji (w polach zwracany jest null).
Luki w dniach Brak danych dla: 3, 18, 19, 20 marca oraz 29 marca 2026 r. z uwagi na przerwy techniczne w działaniu scrapera.
ZKA i pociągi międzynarodowe Autobusy ZKA i pociągi z zagranicy nie figurują w bazie. Wynika to z braków śledzenia trasy na poziomie głównego dostawcy.
Pociągi nocne Dla kursów trwających po północy, dane o opóźnieniach na odcinkach po godzinie 00:00 mogą być niekompletne lub wyzerowane ze względu na dobowy cykl resetowania danych w źródłowym portalu.

Limity zapytań (Rate Limiting)

W celu ochrony bazy danych przed nadmiernym obciążeniem, API posiada limity zapytań per adres IP. Obecny limit wynosi 20 zapytań na minutę z jednego adresu IP.

Dostępne endpointy

GET /train-runs

Pobiera listę skróconych informacji o kursach pociągów w danym dniu. Jest to przydatne do wyszukiwania danego pociągu przed pobraniem jego szczegółów.

Parametry zapytania (Query Parameters):

  • date (opcjonalnie): Data kursów w formacie YYYY-MM-DD (domyślnie wczoraj).
  • number (opcjonalnie): Numer pociągu (lub część, np. "5322").
  • station (opcjonalnie): Wyszukiwanie pociągów, których stacją początkową lub końcową jest dana fraza.
  • offset (opcjonalnie): Paginacja - przesunięcie (domyślnie 0).
  • limit (opcjonalnie): Paginacja - limit wyników (domyślnie 500).

Przykład użycia (cURL):

curl -X 'GET' \
  'https://api.spoznienia.me/train-runs?date=2026-02-17&station=zag%C3%B3rz' \
  -H 'accept: application/json'

Fragment przykładowej odpowiedzi:

[
  {
    "id": "2026021733110",
    "date": "2026-02-17",
    "number": "33110",
    "name": "Wetlina",
    "category": "IC",
    "from_station": "Zagórz",
    "to_station": "Kraków Płaszów",
    "is_domestic": true,
    "occupancy": "Szacowana frekwencja w przedziale 50%-80%",
    "scheduled_departure": "04:55:00",
    "scheduled_arrival": "09:19:00",
    "delay_at_destination": 6
  },
  {
    "id": "2026021730112",
    "date": "2026-02-17",
    "number": "30112",
    "name": "Bieszczady",
    "category": "IC",
    "from_station": "Kraków Główny",
    "to_station": "Zagórz",
    "is_domestic": true,
    "occupancy": "Szacowana frekwencja w przedziale 50%-80%",
    "scheduled_departure": "09:30:00",
    "scheduled_arrival": "13:58:00",
    "delay_at_destination": 0
  }
]

Model danych:

Pole Typ Opis
idstringUnikalny identyfikator kursu (data + numer)
datestringData kursu (YYYY-MM-DD)
numberstringNumer pociągu
namestringNazwa pociągu
categorystringKategoria (np. IC, EIP, TLK)
from_stationstringStacja początkowa całej trasy
to_stationstringStacja końcowa całej trasy
is_domesticbooleanCzy pociąg jest krajowy (true) czy międzynarodowy (false)
occupancystringPrzewidywana frekwencja
scheduled_departurestringPlanowy odjazd ze stacji początkowej (HH:MM:SS)
scheduled_arrivalstringPlanowy przyjazd na stację końcową (HH:MM:SS)
delay_at_destinationintegerOpóźnienie na stacji końcowej (w minutach)
GET /stations/{name}/schedule

Pobiera harmonogram (tablicę odjazdów i przyjazdów) dla konkretnej stacji w zadanym dniu. Pozwala sprawdzić punktualność pociągów zatrzymujących się na danej stacji, uwzględniając przystanki pośrednie.

Parametry ścieżki i zapytania:

  • name (wymagane w URL): Nazwa stacji (np. "Kluczbork", bez rozróżniania małych i wielkich liter).
  • date (opcjonalnie): Data w formacie YYYY-MM-DD (domyślnie wczoraj).

Przykład użycia (Javascript Fetch API):

fetch('https://api.spoznienia.me/stations/krosno/schedule?date=2026-01-07')
  .then(response => response.json())
  .then(data => console.log(data));

Fragment przykładowej odpowiedzi:

[
  {
    "train_number": "33110",
    "train_category": "IC",
    "from_station": "Zagórz",
    "to_station": "Kraków Płaszów",
    "scheduled_arrival": "06:09:00",
    "scheduled_departure": "06:14:00",
    "delay_arrival_min": 0,
    "delay_departure_min": 10,
    "is_delayed": true,
    "train_id": "2026010733110"
  },
  {
    "train_number": "30161",
    "train_category": "TLK",
    "from_station": "Kraków Główny",
    "to_station": "Krosno",
    "scheduled_arrival": "16:05:00",
    "scheduled_departure": null,
    "delay_arrival_min": 0,
    "delay_departure_min": null,
    "is_delayed": false,
    "train_id": "2026010730161"
  }
]

Model danych:

Pole Typ Opis
train_numberstringNumer pociągu
train_categorystringKategoria pociągu (np. IC, TLK)
from_stationstringStacja początkowa trasy
to_stationstringStacja końcowa trasy
scheduled_arrivalstringPlanowany czas przyjazdu na badaną stację (HH:MM:SS)
scheduled_departurestringPlanowany czas odjazdu z badanej stacji (HH:MM:SS)
delay_arrival_minintegerRzeczywiste opóźnienie przyjazdu (min)
delay_departure_minintegerRzeczywiste opóźnienie odjazdu (min)
is_delayedbooleanFlagowa informacja czy pociąg jest opóźniony na tej stacji
train_idstringUnikalny identyfikator pociągu w bazie
GET /train-runs/{train_id}

Pobiera pełne dane o wybranym kursie pociągu (uzyskane m.in. z endpointu `/train-runs`), włączając w to bardzo szczegółową listę wszystkich przystanków, opóźnień na każdym z nich oraz zgłoszonych utrudnień (awarie, blokady trasy itp.).

Parametry ścieżki i zapytania:

  • train_id (wymagane w URL): Unikalny identyfikator pociągu. Zbudowany z ciągów (YYYYMMDD + nr pociągu np. 202603165322).

Przykład użycia (cURL):

curl -X 'GET' \
  'https://api.spoznienia.me/train-runs/2026031233112' \
  -H 'accept: application/json'

Fragment przykładowej odpowiedzi:

{
  "id": "2026031233112",
  "date": "2026-03-12",
  "number": "33112",
  "name": "Bieszczady",
  "category": "IC",
  "from_station": "Zagórz",
  "to_station": "Kraków Główny",
  "is_domestic": true,
  "occupancy": "Szacowana frekwencja poniżej 50%",
  "scheduled_departure": "14:50:00",
  "scheduled_arrival": "19:21:00",
  "delay_at_destination": 0,
  "stops": [
    {
      "station_name": "Zagórz",
      "stop_order": 1,
      "arrival_time": null,
      "departure_time": "14:50:00",
      "delay_minutes_arrival": null,
      "delay_minutes_departure": 0,
      "distance_from_start_km": 0.0,
      "is_domestic": true,
      "latitude": 49.5165,
      "longitude": 22.2687,
      "difficulties": []
    },
    {
      "station_name": "Krosno",
      "stop_order": 4,
      "arrival_time": "16:06:00",
      "departure_time": "16:16:00",
      "delay_minutes_arrival": 0,
      "delay_minutes_departure": 7,
      "distance_from_start_km": 46.1,
      "is_domestic": true,
      "latitude": 49.6917,
      "longitude": 21.7513,
      "difficulties": [
        {
          "description": "Oczekiwanie na skomunikowanie",
          "location": null
        }
      ]
    },
    {
      "station_name": "Kraków Główny",
      "stop_order": 13,
      "arrival_time": "19:21:00",
      "departure_time": null,
      "delay_minutes_arrival": 0,
      "delay_minutes_departure": null,
      "distance_from_start_km": 247.1,
      "is_domestic": true,
      "latitude": 50.0667,
      "longitude": 19.9472,
      "difficulties": []
    }
  ]
}

Model danych (stops):

Pole Opis
station_nameNazwa stacji pośredniej
stop_orderKolejność przystanku na trasie (od 1)
arrival_timePlanowy czas przyjazdu (HH:MM:SS)
departure_timePlanowy czas odjazdu (HH:MM:SS)
delay_minutes_arrivalOpóźnienie przyjazdu (minuty)
delay_minutes_departureOpóźnienie odjazdu (minuty)
distance_from_start_kmDystans od stacji początkowej (km) - dotyczy tylko stacji krajowych
is_domesticCzy stacja znajduje się na terenie Polski (true/false)
latitudeSzerokość geograficzna stacji (opcjonalnie)
longitudeDługość geograficzna stacji (opcjonalnie)
difficultiesLista obiektów ze szczegółami utrudnienia (pola: description, location)