Dokumentace

Jak feedy konzumovat a co v nich čekat.

Endpointy

Cesta	Typ	Cache	Popis
`GET /gtfs.zip`	`application/zip`	1 h, `ETag`	Statický feed. Přestavuje se jednou denně v noci.
`GET /gtfs-rt.pb`	`application/x-protobuf`	15 s	VehiclePositions a TripUpdates v jedné zprávě.
`GET /gtfs-rt.json`	`application/json`	—	Totéž pro ladění. Nepoužívat v provozu, formát není stabilní.
`GET /vehicles.json`	`application/json`	15 s	Vozidla s vyřešenými názvy zastávek a zpožděním. Není to standard — pro ten je tu `/gtfs-rt.pb` — ale ušetří konzumentovi držet celý jízdní řád jen kvůli zobrazení jedné polohy.
`GET /healthz`	`application/json`	—	Stáří feedů a poslední chyba. Vrací 503, když jsou data zastaralá.

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á.

Typ	Tvar	Příklad
Stanice	`S<číslo>`	`S16` — Hlavní nádraží
Nástupiště	`S<číslo>P<nástupiště>`	`S16P2`
Linka	`L<číslo>`	`L9`
Spoj	`L<linka>C<spoj>`	`L9C115`

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ář

Pět služeb: pracovní dny, sobota, neděle, víkend a denně. Státní svátky se přepínají na nedělní provoz přes calendar_dates.txt, včetně pohyblivých Velikonoc.

Geometrie tras

Zdrojové API geometrii nemá, takže shapes.txt vzniká 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.

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.