ref: 78d4d946149652433c2cdd60774b5c24c35df86d
localities/transitous.adoc
= 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