Dokumentace

Jak feedy konzumovat a co v nich čekat.

Endpointy

Feed se obnovuje každých 15 sekund; častější dotazování nemá smysl.

curl -s https://…/gtfs-rt.pb -o gtfs-rt.pb
curl -s https://…/gtfs.zip -o gtfs.zip

Identifikátory

ID jsou odvozená z číslování DPMP, takže jsou napříč oběma feedy stabilní a čitelná.

Jízdní řády i realtime odkazují na nástupiště, ne na stanici. Stanice existuje jako parent_station, aby šlo nástupiště seskupit a rozumět přestupům mezi nimi.

Co ve feedu čekat

Zpoždění

Zpoždění se měří — sleduje se, kdy vůz projede zastávkou, a porovná se s jízdním řádem. Rozlišení je zhruba 15 sekund. Jakmile je změřeno, drží se po zbytek spoje konstantní: jízdní řády sice mají rezervu a vůz ji často dožene, ale předpovídat doháněni by znamenalo model, ne měření.

Vozidlo, u kterého zpoždění změřené není — typicky čeká na výchozí zastávce a ještě nevyjelo — dostane VehiclePosition, ale žádný TripUpdate. Nulové zpoždění by tvrdilo, že jede přesně, což z dat nevyplývá. Takových vozidel bývá kolem 40 %.

Kalendář — z CIS, ne z API

Dny provozu jsou jediný údaj, který nepochází z API dopravního podniku. Kódy dnů provozu, které API posílá, zhruba u třetiny spojů neodpovídají vyvěšenému jízdnímu řádu — spoj 46 linky 1 (06:36 ze Slovany,točna) je podle jízdního řádu i podle celostátního registru CIS JŘ pracovní den, podle API víkend. Feed proto bere kalendáře z CIS, kam DPMP jízdní řády odevzdává jako primární zdroj; dopravnímu podniku je rozpor nahlášený. Zhruba 2 % spojů v CIS protějšek nemají a těm zůstávají kódy z API.

Výsledkem je necelá dvacítka služeb: kromě pracovních dnů, soboty, neděle a denního provozu i sezónní varianty, protože DPMP jezdí jiné pracovní dny podle školního vyučování. Rozdíly oproti týdennímu vzorci — včetně státních svátků, kdy síť jede nedělní provoz — jsou v calendar_dates.txt.

Kolem změny jízdního řádu je feed neúplný. Nový jízdní řád spoje přečísluje, takže spoj, jehož časy se po změně mění, má poslední den provozu právě den před ní — feed o něm dál neví nic a nic si nedomýšlí. Noční přestavba to srovná, jakmile dopravní podnik nový řád vydá. Kdo si feed stahuje, ať to dělá denně.

Geometrie tras — odhad

Tvar trasy mezi zastávkami není údaj dopravního podniku. Zastávky, časy a spoje pocházejí přímo z jeho API, ale geometrii jízdy po ulicích nikdo nepublikuje v podobě, ze které by šel shapes.txt sestavit — dopočítává se proto zroutováním posloupnosti zastávek přes Valhallu nad daty OpenStreetMap, autobusovým profilem.

Spoje sdílejí trasy — 2 728 spojů se scvrkne na 218 různých posloupností — takže shape má každý spoj. shape_dist_traveled je v metrech a je vyplněné jak v shapes.txt, tak v stop_times.txt. Zastávky leží od trasy v mediánu 6,6 m, nejvíc 10 m.

Data od zdroje se získat nepodařilo: API sice endpoint s geometrií má, ale vrací jednu reprezentativní trasu na linku, ne na spoj, a varianty linek se od ní liší i o kilometry. Praktický dopad pro konzumenta: routování může zvolit jinou, byť průjezdnou ulici, a pár desítek takových míst je známo. Měření a podrobnosti v docs/upstream-api.md.

Co ve feedu není

• transfers.txt, frequencies.txt — pro tuhle síť nejsou potřeba.
• Mimořádnosti (ServiceAlerts) — zdroj je má, ale za dobu vývoje nevrátil ani jednu, takže se nedá odvodit jejich struktura.

Známé nepřesnosti

• Tři zastávky (Vápenka, Svítkov západ, Mikulovice) v podkladových datech DPMP vůbec nemají souřadnice. Doplněny jsou z OpenStreetMap. Týká se to přes 250 spojů, takže je vynechat nešlo.
• Tři nástupiště, která DPMP neuvádí, jsou umístěna na souřadnice své stanice — nepřesnost v řádu desítek metrů.
• Zastávky, kam podle jízdních řádů nic nejede, jsou z feedu vyřazené. Změny v této množině se sledují mezi přestavbami, protože bývají důsledkem výluky.

Licence a citace

Jízdní řády a polohy vozidel pocházejí od Dopravního podniku města Pardubic a.s. Kód této služby je AGPL-3.0. Doplněné souřadnice tří zastávek pocházejí z OpenStreetMap a podléhají ODbL.