Merge branch 'master' of kumig.it:kumitterer/oebb_py
This commit is contained in:
commit
d52dbd8384
132
README.md
Normal file
132
README.md
Normal file
|
@ -0,0 +1,132 @@
|
|||
# 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 im Weinviertel&to=
|
||||
Götzendorf/Leitha&time=12:00)
|
||||
* [Same request using time of arrival]
|
||||
(https://bahnapi.xyz/?type=conn&from=Wolkersdorf im Weinviertel&to=
|
||||
Götzendorf/Leitha&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&json)
|
Loading…
Reference in a new issue