From 5613f49e08f31bace4e78fbf5e9e7417d175cb47 Mon Sep 17 00:00:00 2001 From: Klaus-Uwe Mitterer Date: Thu, 28 Sep 2017 20:53:28 +0200 Subject: [PATCH 1/4] Add short documentation --- README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7a4bb2c --- /dev/null +++ b/README.md @@ -0,0 +1,130 @@ +# Python3 ÖBB API + +This project aims to provide a functional API for the Austrian Federal Railways +(Österreichische Bundesbahnen, ÖBB). It has three core features/request types: + +* Search for Public Transportation stops by name ("val") +* Search for Public Transportation stops by coordinates ("nearby") +* Search for Public Transportation connections between two stops ("conn") + +## Request + +A request is made by sending a GET or POST request to the endpoint, e.g. +[https://bahnapi.xyz/](https://bahnapi.xyz), with a "type" parameter and +additional parameters as required for the request type. + +The example requests below use GET for obvious reasons, but passing the same +parameters in a POST request will yield the same results. + +### Search for stops by name ("val") + +The following parameters are required for this type of request: + +* "type": "val" +* "name": Name of the station + +This request will return a list of station names most closely matching the name +provided in the request as well as corresponding station IDs, ordered by match +quality. + +* [Example "val" request](https://bahnapi.xyz/?type=val&name=Graz) + +### Search for stops by coordinates ("nearby") + +The following parameters are required for this type of request: + +* "type": "nearby" +* "lat": Decimal latitude +* "lon": Decimal longitude + +The following optional parameter is accepted: + +* "distance": Maximum distance in meters (as the crow flies, default: 1000) + +This request will return a list of station names closest to given coordinates +as well as the corresponding station IDs and distance in meters (as the crow +flies), ordered by distance. + +The "distance" parameter defaults to 1000, i.e. stations up to 1,000 meters from +the provided coordinates will be returned. You may want to increase or decrease +this value, but setting it too high may cause the request to time-out. + +This makes a request to [OpenStreetMap](https://osm.org/) to find the stations +closest to given coordinates. Issues may occur where station names in OSM differ +from those used internally by ÖBB. + +* [Example "nearby" request](https://bahnapi.xyz/?type=nearby&lat=47.489& +lon=9.69) + +### Search for connections between two stops ("conn") + +The following parameters are required for this type of request: + +* "type": "conn" +* "from": Name or ID (as returned by "val") of the station of departure +* "to": Name or ID of the station of arrival + +The following optional parameters are accepted: + +* "count": Number of connections to return (default: 1) +* "date": Date on which to find a connection (e.g. 31.12.2017, default: today) +* "time": Time at which to find a connection (e.g. 20:00, default: current time) +* "mode": May be set to "arr" if "time" should be considered time of arrival +* "details": May be set to return additional details to connections (see below) + +This request will return a list of connections between the two stations given in +the "from" and "to" parameters, ordered by time of departure. + +It is not required that the station names provided in "from" and "to" exactly +match the stations' official names. A "val" request will always be made +implicitly and the closest match will be used. + +* [Example "conn" request from "Leibitz" to "Kaldorf"](https://bahnapi.xyz/? +type=conn&from=Leibitz&to=Kaldorf) + +By default, the response will not include some information, including at which +stations a change to a different service is required, if applicable. It will, +however, return the total number of changes. If additional information is +required, it may be requested by adding the "details" parameter to the request. +Note that this request is going to take considerably longer to process. If at +all possible, do not set "count" higher than 1 when requesting details as too +many connections may cause the query to time-out. + +* [Example "conn" request without details](https://bahnapi.xyz/?type=conn&from= +Strobl&to=Wien) +* [Same request with details](https://bahnapi.xyz/?type=conn&from=Strobl&to=Wien +&details) + +If "count" is not set, one connection will be returned. This value may safely be +increased up to 6 if "details" is not set. + +* [Example "conn" request for five connections](https://bahnapi.xyz/?type=conn& +from=Thörl&to=Pama&count=5) + +The provided "time" will by default be considered as the requested time of +departure. To use it as the time of arrival instead, the "mode" parameter may +be set to "arr". + +* [Example "conn" request using time of departure](https://bahnapi.xyz/? +type=conn&from=Wolkersdorf&to=Götzendorf&time=12:00) +* [Same request using time of arrival](https://bahnapi.xyz/?type=conn&from= +Wolkersdorf&to=Götzendorf&time=12:00&mode=arr) + +### Short requests + +For "val" and "conn" requests, it is possible to use shorter requests by passing +arguments in the path. Paths consisting of one part (i.e. /value) will be +handled as "val" requests while those consisting of two parts (/value1/value2) +will be handled as "conn" requests. Optional values can be passed as GET or POST +parameters as usual. + +* [Example short "val" request](https://bahnapi.xyz/Kanfanar) +* [Example short "conn" request](https://bahnapi.xyz/Bregenz/Neusiedl am See) + +### Output format + +By default, the API returns its results as XML. If you prefer JSON, you may add +the "json" parameter to your query. + +* [Example "nearby" request returning JSON](https://bahnapi.xyz/?type=nearby& +lat=48.293&lon=16.482) \ No newline at end of file From 7fe58e503fc88f72755b41aba1a7a8ee20c32e2e Mon Sep 17 00:00:00 2001 From: Klaus-Uwe Mitterer Date: Thu, 28 Sep 2017 20:57:05 +0200 Subject: [PATCH 2/4] Apparently, GitLab doesn't handle line breaks in URLs properly. --- README.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 7a4bb2c..0ebb26f 100644 --- a/README.md +++ b/README.md @@ -53,8 +53,8 @@ This makes a request to [OpenStreetMap](https://osm.org/) to find the stations closest to given coordinates. Issues may occur where station names in OSM differ from those used internally by ÖBB. -* [Example "nearby" request](https://bahnapi.xyz/?type=nearby&lat=47.489& -lon=9.69) +* [Example "nearby" request] +(https://bahnapi.xyz/?type=nearby&lat=47.489&lon=9.69) ### Search for connections between two stops ("conn") @@ -79,8 +79,8 @@ It is not required that the station names provided in "from" and "to" exactly match the stations' official names. A "val" request will always be made implicitly and the closest match will be used. -* [Example "conn" request from "Leibitz" to "Kaldorf"](https://bahnapi.xyz/? -type=conn&from=Leibitz&to=Kaldorf) +* [Example "conn" request from "Leibitz" to "Kaldorf"] +(https://bahnapi.xyz/?type=conn&from=Leibitz&to=Kaldorf) By default, the response will not include some information, including at which stations a change to a different service is required, if applicable. It will, @@ -90,25 +90,26 @@ Note that this request is going to take considerably longer to process. If at all possible, do not set "count" higher than 1 when requesting details as too many connections may cause the query to time-out. -* [Example "conn" request without details](https://bahnapi.xyz/?type=conn&from= -Strobl&to=Wien) -* [Same request with details](https://bahnapi.xyz/?type=conn&from=Strobl&to=Wien -&details) +* [Example "conn" request without details] +(https://bahnapi.xyz/?type=conn&from=Strobl&to=Wien) +* [Same request with details] +(https://bahnapi.xyz/?type=conn&from=Strobl&to=Wien&details) If "count" is not set, one connection will be returned. This value may safely be increased up to 6 if "details" is not set. -* [Example "conn" request for five connections](https://bahnapi.xyz/?type=conn& -from=Thörl&to=Pama&count=5) +* [Example "conn" request for five connections] +(https://bahnapi.xyz/?type=conn&from=Thörl&to=Pama&count=5) The provided "time" will by default be considered as the requested time of departure. To use it as the time of arrival instead, the "mode" parameter may be set to "arr". -* [Example "conn" request using time of departure](https://bahnapi.xyz/? -type=conn&from=Wolkersdorf&to=Götzendorf&time=12:00) -* [Same request using time of arrival](https://bahnapi.xyz/?type=conn&from= -Wolkersdorf&to=Götzendorf&time=12:00&mode=arr) +* [Example "conn" request using time of departure] +(https://bahnapi.xyz/?type=conn&from=Wolkersdorf&to=Götzendorf&time=12:00) +* [Same request using time of arrival] +(https://bahnapi.xyz/?type=conn&from=Wolkersdorf&to=Götzendorf +&time=12:00&mode=arr) ### Short requests @@ -126,5 +127,5 @@ parameters as usual. By default, the API returns its results as XML. If you prefer JSON, you may add the "json" parameter to your query. -* [Example "nearby" request returning JSON](https://bahnapi.xyz/?type=nearby& -lat=48.293&lon=16.482) \ No newline at end of file +* [Example "nearby" request returning JSON] +(https://bahnapi.xyz/?type=nearby&lat=48.293&lon=16.482) \ No newline at end of file From 749659804a32a340f4410841fcff1b07d29a32f2 Mon Sep 17 00:00:00 2001 From: Klaus-Uwe Mitterer Date: Thu, 28 Sep 2017 21:00:15 +0200 Subject: [PATCH 3/4] GitLab is painful at times. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0ebb26f..83abf7e 100644 --- a/README.md +++ b/README.md @@ -106,10 +106,11 @@ departure. To use it as the time of arrival instead, the "mode" parameter may be set to "arr". * [Example "conn" request using time of departure] -(https://bahnapi.xyz/?type=conn&from=Wolkersdorf&to=Götzendorf&time=12:00) +(https://bahnapi.xyz/?type=conn&from=Wolkersdorf im Weinviertel&to= +Götzendorf/Leitha&time=12:00) * [Same request using time of arrival] -(https://bahnapi.xyz/?type=conn&from=Wolkersdorf&to=Götzendorf -&time=12:00&mode=arr) +(https://bahnapi.xyz/?type=conn&from=Wolkersdorf im Weinviertel&to= +Götzendorf/Leitha&time=12:00&mode=arr) ### Short requests From 55625175b2b8a869191be9209fd0b77519f1bab2 Mon Sep 17 00:00:00 2001 From: Klaus-Uwe Mitterer Date: Thu, 28 Sep 2017 21:06:25 +0200 Subject: [PATCH 4/4] Forgot json parameter... --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 83abf7e..2a04cd2 100644 --- a/README.md +++ b/README.md @@ -129,4 +129,4 @@ By default, the API returns its results as XML. If you prefer JSON, you may add the "json" parameter to your query. * [Example "nearby" request returning JSON] -(https://bahnapi.xyz/?type=nearby&lat=48.293&lon=16.482) \ No newline at end of file +(https://bahnapi.xyz/?type=nearby&lat=48.293&lon=16.482&json) \ No newline at end of file