Author: Adam Evyčędo <git@apiote.xyz>
add transitous documentation
localities.adoc | 5 localities/transitous.adoc | 750 ++++++++++++++++++++++++++++++++++++++++
diff --git a/localities/transitous.adoc b/localities/transitous.adoc new file mode 100644 index 0000000000000000000000000000000000000000..33a54a8d3665b1fda955ed2d05e3ff4cd210c02b --- /dev/null +++ b/localities/transitous.adoc @@ -0,0 +1,750 @@ += Transitous + +https://transitous.org/ + +== API + +Upstream documentation: + +* https://routing.spline.de/doc/index.html +* https://motis-project.de/docs/api/ + +=== Searching stops + +.Request documentation +[source,json] +---- +{ + "destination": { + "type": "Module", + "target": "/guesser" + }, + "content_type": "StationGuesserRequest", + "content": { + "input": "$query", # query + "gues_count": "$count" # how many results to return + } +} +---- + +.Request example +[source,sh] +---- +curl 'https://routing.spline.de/api/' \ + -H 'content-type: application/json' \ + --data-raw '{"destination":{"type":"Module","target":"/guesser"},"content_type":"StationGuesserRequest","content":{"input":"tower hill","guess_count":6}}' +---- + +.Response documentation +[source,json] +---- +{ + "content": { + "guesses": [ + { + "id": "$stopID", # stop ID + "name": "$stopName", # stop name + "pos": { + "lat": $latitude, # stop latitude + "lng": $longitude # stop longitude + } + }, + # … + ] + }, + "content_type": "StationGuesserResponse", + "destination": { + "target": "", + "type": "Module" + }, + "id": 1 +} +---- + +.Response example +[source,json] +---- +{ + "content": { + "guesses": [ + { + "id": "gb-great-britain_50-1-430G05308", + "name": "Tower Hill", + "pos": { + "lat": 52.534782, + "lng": -1.918755 + } + }, + { + "id": "gb-northern-ireland_51-49-700000008267", + "name": "Tower Hill", + "pos": { + "lat": 54.352318, + "lng": -6.645357 + } + }, + { + "id": "gb-great-britain_50-1-227G00091138", + "name": "Tower Hill", + "pos": { + "lat": 53.48921, + "lng": -0.856088 + } + }, + { + "id": "gb-great-britain_50-1-400G4407356A", + "name": "Tower Hill", + "pos": { + "lat": 51.217354, + "lng": -0.448421 + } + }, + { + "id": "gb-great-britain_50-1-390G70148", + "name": "Tower Hill", + "pos": { + "lat": 52.44609, + "lng": 1.568928 + } + }, + { + "id": "gb-great-britain_50-1-2400A030890A", + "name": "Tower Hill", + "pos": { + "lat": 51.29039, + "lng": 0.377833 + } + } + ] + }, + "content_type": "StationGuesserResponse", + "destination": { + "target": "", + "type": "Module" + }, + "id": 1 +} +---- + +=== Stops nearby + +.Request documentation +[source,json] +---- +{ + "destination": { + "type": "Module", + "target": "/lookup/geo_station" + } + "content_type": "LookupGeoStationRequest", + "content": { + "max_radius": $radius, # radius from centre in metres + "pos": { + "lat": $latitude, # latitude of the centre + "lng": $longitude # longitude of the centre + } + } +} +---- + +.Request example +[source,sh] +---- +curl 'https://routing.spline.de/api/' \ + -H 'content-type: application/json' \ + --data-raw '{"destination":{"type":"Module","target":"/lookup/geo_station"},"content_type":"LookupGeoStationRequest","content":{"max_radius":1000,"pos":{"lat":52.412, "lng":16.894}}}' +---- + +.Response documentation +[source,json] +---- +{ + "content": { + "stations": [ + { + "id": "$stopID", # stop ID + "name": "$stopName", # stop name + "pos": { + "lat": $latitude, # stop latitude + "lng": $longitude # stop longitude + } + }, + # … + ] + }, + "content_type": "LookupGeoStationResponse", + "destination": { + "target": "", + "type": "Module" + }, + "id": 1 +} +---- + +.Response example +[source,json] +---- +{ + "content": { + "stations": [ + { + "id": "pl-Poznań_62", + "name": "Polna", + "pos": { + "lat": 52.41424, + "lng": 16.896698 + } + }, + { + "id": "pl-Poznań_63", + "name": "Polna", + "pos": { + "lat": 52.414215, + "lng": 16.897202 + } + }, + { + "id": "pl-Poznań_755", + "name": "Polna Szpital", + "pos": { + "lat": 52.409008, + "lng": 16.893578 + } + }, + { + "id": "pl-Poznań_1452", + "name": "Żeromskiego", + "pos": { + "lat": 52.414555, + "lng": 16.890738 + } + }, + { + "id": "pl-Poznań_756", + "name": "Polna Szpital", + "pos": { + "lat": 52.409225, + "lng": 16.890743 + } + }, + { + "id": "pl-Poznań_67", + "name": "Bukowska", + "pos": { + "lat": 52.410053, + "lng": 16.888826 + } + }, + { + "id": "pl-Poznań_66", + "name": "Bukowska", + "pos": { + "lat": 52.41, + "lng": 16.888638 + } + }, + { + "id": "pl-Poznań_60", + "name": "Żeromskiego", + "pos": { + "lat": 52.415543, + "lng": 16.890825 + } + }, + { + "id": "pl-Poznań_1450", + "name": "Żeromskiego", + "pos": { + "lat": 52.416077, + "lng": 16.89216 + } + }, + { + "id": "pl-Poznań_61", + "name": "Żeromskiego", + "pos": { + "lat": 52.41574, + "lng": 16.890362 + } + }, + { + "id": "pl-Poznań_758", + "name": "Bukowska", + "pos": { + "lat": 52.409256, + "lng": 16.888174 + } + }, + { + "id": "pl-Poznań_752", + "name": "Szylinga", + "pos": { + "lat": 52.408333, + "lng": 16.89875 + } + }, + { + "id": "pl-Poznań_1451", + "name": "Żeromskiego", + "pos": { + "lat": 52.416557, + "lng": 16.891827 + } + }, + { + "id": "pl-Poznań_759", + "name": "Grodziska", + "pos": { + "lat": 52.410072, + "lng": 16.88585 + } + }, + { + "id": "pl-Poznań_751", + "name": "Szylinga", + "pos": { + "lat": 52.407883, + "lng": 16.900095 + } + }, + { + "id": "pl-Poznań_754", + "name": "Kraszewskiego", + "pos": { + "lat": 52.408916, + "lng": 16.901783 + } + }, + { + "id": "pl-Poznań_760", + "name": "Grodziska", + "pos": { + "lat": 52.410122, + "lng": 16.884207 + } + }, + { + "id": "pl-Poznań_1463", + "name": "Kościelna", + "pos": { + "lat": 52.413483, + "lng": 16.904005 + } + }, + { + "id": "pl-Poznań_65", + "name": "Rynek Jeżycki", + "pos": { + "lat": 52.412537, + "lng": 16.90477 + } + }, + { + "id": "pl-Poznań_4272", + "name": "Kraszewskiego", + "pos": { + "lat": 52.40773, + "lng": 16.902296 + } + }, + { + "id": "pl-Poznań_1464", + "name": "Kościelna", + "pos": { + "lat": 52.41357, + "lng": 16.904663 + } + }, + { + "id": "pl-Poznań_64", + "name": "Rynek Jeżycki", + "pos": { + "lat": 52.412224, + "lng": 16.905642 + } + }, + { + "id": "pl-Poznań_748", + "name": "Matejki", + "pos": { + "lat": 52.40627, + "lng": 16.900963 + } + }, + { + "id": "pl-Poznań_622", + "name": "Ogrody", + "pos": { + "lat": 52.416683, + "lng": 16.885157 + } + }, + { + "id": "pl-Poznań_83", + "name": "Matejki", + "pos": { + "lat": 52.40579, + "lng": 16.900932 + } + }, + { + "id": "pl-Poznań_750", + "name": "Matejki", + "pos": { + "lat": 52.405228, + "lng": 16.899405 + } + }, + { + "id": "pl-Poznań_4032", + "name": "Niestachowska", + "pos": { + "lat": 52.41986, + "lng": 16.894829 + } + }, + { + "id": "pl-Poznań_749", + "name": "Matejki", + "pos": { + "lat": 52.40486, + "lng": 16.899946 + } + }, + { + "id": "pl-Poznań_4033", + "name": "Niestachowska", + "pos": { + "lat": 52.420006, + "lng": 16.894829 + } + }, + { + "id": "pl-Poznań_59", + "name": "Ogrody", + "pos": { + "lat": 52.416363, + "lng": 16.882902 + } + }, + { + "id": "pl-Poznań_769", + "name": "Opalenicka", + "pos": { + "lat": 52.404903, + "lng": 16.88735 + } + }, + { + "id": "pl-Poznań_770", + "name": "Opalenicka", + "pos": { + "lat": 52.40478, + "lng": 16.887516 + } + }, + { + "id": "pl-Poznań_1465", + "name": "Jeżycka", + "pos": { + "lat": 52.416206, + "lng": 16.90584 + } + }, + { + "id": "pl-Poznań_4030", + "name": "Św. Wawrzyńca", + "pos": { + "lat": 52.418835, + "lng": 16.901928 + } + }, + { + "id": "pl-Poznań_627", + "name": "Szpitalna", + "pos": { + "lat": 52.410828, + "lng": 16.880344 + } + }, + { + "id": "pl-Poznań_4031", + "name": "Św. Wawrzyńca", + "pos": { + "lat": 52.41869, + "lng": 16.90268 + } + }, + { + "id": "pl-Poznań_72", + "name": "Wojskowa", + "pos": { + "lat": 52.40341, + "lng": 16.892479 + } + }, + { + "id": "pl-Poznań_58", + "name": "Ogrody", + "pos": { + "lat": 52.417053, + "lng": 16.882463 + } + }, + { + "id": "pl-Poznań_621", + "name": "Ogrody", + "pos": { + "lat": 52.416927, + "lng": 16.882246 + } + }, + { + "id": "pl-Poznań_4079", + "name": "Ogrody", + "pos": { + "lat": 52.416294, + "lng": 16.881414 + } + }, + { + "id": "pl-Poznań_620", + "name": "Ogrody", + "pos": { + "lat": 52.41691, + "lng": 16.88181 + } + } + ] + }, + "content_type": "LookupGeoStationResponse", + "destination": { + "target": "", + "type": "Module" + }, + "id": 1 +} +---- + +=== Departures for single stop + +.Request documentation +[source,json] +---- +{ + "destination": { + "type": "Module", + "target": "/railviz/get_station" + }, + "content_type": "RailVizStationRequest", + "content": { + "station_id": "$stopID", # stop ID + "time" $timestamp, # UNIX timestamp + "event_count": $count, # how many departures to return + "direction": "$direction", # LATER or BOTH or EARLIER; meaning unknown, possibly in relation to the time paramer + "by_schedule_time": $byScheduleTime # boolean; meaning unknown + } +} +---- + +.Request example +[source,sh] +---- +curl 'https://routing.spline.de/api/' \ + -H 'content-type: application/json' \ + --data-raw '{"destination":{"type":"Module","target":"/railviz/get_station"},"content_type":"RailVizStationRequest","content":{"station_id":"pl-Poznań_62","time": 1726744921, "event_count": 1, "direction": "LATER", "by_schedule_time": true}}' +---- + +.Response documentation +[source,json] +---- +{ + "content": { + "events": [ + { + "event": { + "reason": "$reason", # enum describing time source (https://motis-project.de/docs/api/connection.html#reason) + "schedule_time": $scheduleTime, # schedule UNIX timestamp of the event + "schedule_track": "$scheduleTrack", # rail track of the event in schedule + "time": $time, # effective UNIX timestamp of the event + "track": "$track", # effective rail track of the event + "valid": $valid # boolean flag; false for departures from final terminus and arrivals to initial terminus + }, + "trips": [ + { + "id": { # https://motis-project.de/docs/api/buildingblocks.html#trip-id + "id": "$tripID", # trips ID + "line_id": "$lineID", # line ID + "station_id": "$stopID", # stop ID + "target_station_id": "$finalTerminusID", # final terminus stop ID + "target_time": $targetTime, # UNIX timestamp of the arrival at the destination + "time": $firstTime, # first departure time + "train_nr": $trainNumber # unique train number at the first departure + }, + "transport": { + "clasz": $lineType, # line type (https://motis-project.de/docs/api/connection.html#clasz-type-integer) + "direction": "$lineHeadsign", # direction of the vehicle + "line_id": "$lineID", # line ID + "name": "$lineName", # line name + "provider": "$operatorName", # operator name + "provider_url": "$operatorWebsite", # operator website + "range": { # range of stops indices to which the information applies + "from": 0, + "to": 0 + }, + "route_color": "$lineColour" # line colour + } + } + ], + "type": "$eventType" # ARR or DEP; there are always two events for one requested + } + ], + "station": { + "id": "$stationID", # station ID (different from stop ID) + "name": "$stopName", # station name + "pos": { + "lat": $latitude, # stop latitude + "lng": $longitude # stop longitude + } + } + }, + "content_type": "RailVizStationResponse", + "destination": { + "target": "", + "type": "Module" + }, + "id": 1 +} +---- + +.Response example +[source,json] +---- +{ + "content": { + "events": [ + { + "event": { + "reason": "SCHEDULE", + "schedule_time": 1726744920, + "schedule_track": "", + "time": 1726744920, + "track": "", + "valid": true + }, + "trips": [ + { + "id": { + "id": "pl-Poznań_1_5486280^N+", + "line_id": "2", + "station_id": "pl-Poznań_193", + "target_station_id": "pl-Poznań_58", + "target_time": 1726745160, + "time": 1726743060, + "train_nr": 0 + }, + "transport": { + "clasz": 9, + "direction": "Ogrody", + "line_id": "2", + "name": "Tram 2", + "provider": "Miejskie Przedsiębiorstwo Komunikacyjne Sp. z o.o. w Poznaniu", + "provider_url": "http://www.mpk.poznan.pl", + "range": { + "from": 0, + "to": 0 + }, + "route_color": "72c4e7" + } + } + ], + "type": "DEP" + }, + { + "event": { + "reason": "SCHEDULE", + "schedule_time": 1726744920, + "schedule_track": "", + "time": 1726744920, + "track": "", + "valid": true + }, + "trips": [ + { + "id": { + "id": "pl-Poznań_1_5486280^N+", + "line_id": "2", + "station_id": "pl-Poznań_193", + "target_station_id": "pl-Poznań_58", + "target_time": 1726745160, + "time": 1726743060, + "train_nr": 0 + }, + "transport": { + "clasz": 9, + "direction": "Ogrody", + "line_id": "2", + "name": "Tram 2", + "provider": "Miejskie Przedsiębiorstwo Komunikacyjne Sp. z o.o. w Poznaniu", + "provider_url": "http://www.mpk.poznan.pl", + "range": { + "from": 0, + "to": 0 + }, + "route_color": "72c4e7" + } + } + ], + "type": "ARR" + } + ], + "station": { + "id": "62", + "name": "Polna", + "pos": { + "lat": 52.41424, + "lng": 16.896698 + } + } + }, + "content_type": "RailVizStationResponse", + "destination": { + "target": "", + "type": "Module" + }, + "id": 1 +} +---- + + +=== Get vehicles on map + +.Request documentation +[source,json] +---- +{ + "destination": { + "type": "Module", + "target": "/railviz/get_trains" + }, + "content_type": "RailVizTrainsRequest", + "content": { + "zoom_bounds": $zoomBounds # integer; meaning unknown + "zoom_geo": $zoomGeo # integer; meaning unknown + "corner1": { # which corner is which, and does it matter? + "lat": $latitude, # corner latitude + "lng": $longitude # corner longitude + } + "corner2": { + "lat": $latitude, # corner latitude + "lng": $longitude # corner longitude + } + "max_trains": $maxTrains # integer; probably max number of results + "last_trains": $lastTrain # integer; meaning unknown + "start_time": $startTime # integer; meaning unknown + "end_time": $endTime # integer; meaning unknown + } +} +---- + +Response doesn't include vehicle positions. They must probably be interpolated from last and next stops diff --git a/localities.adoc b/localities.adoc index 864de535296868e85888604196bfa417bdd1d97f..299e04bf74ed7de4c4dc89a4833580b7cd46674e 100644 --- a/localities.adoc +++ b/localities.adoc @@ -11,7 +11,10 @@ * [[US: Rock Hill, SC My Ride|localities/rockhill_myride]] == Being worked on +* UK/GB provided by UK Depertment for Transport +* NL provided by OVapi +* [[Transitous|localities/transitous]] + == Future -* UK/GB provided by UK Depertment for Transport