166 lines
6.6 KiB
Markdown
166 lines
6.6 KiB
Markdown
# Python3 ÖBB API
|
|
|
|
This project aims to provide a functional API for the Austrian Federal Railways
|
|
(Österreichische Bundesbahnen, ÖBB). It has four 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")
|
|
* Search for the current location of a train ("radar")
|
|
|
|
## 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: 6)
|
|
* "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)
|
|
* "via": Return connections passing through a specific station
|
|
|
|
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 about two to three times as long to
|
|
process.
|
|
|
|
* [Example "conn" request without details]
|
|
(https://bahnapi.xyz/?type=conn&from=Koppl&to=Wien)
|
|
* [Same request with details]
|
|
(https://bahnapi.xyz/?type=conn&from=Koppl&to=Wien&details)
|
|
|
|
If "count" is not set, six connection will be returned, which is the maximum
|
|
retrievable at once.
|
|
|
|
* [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)
|
|
|
|
To make sure the connection passes through a specific station, the name or ID
|
|
of that station may be passed as a "via" parameter. Up to three "via" parameters
|
|
may be passed in a single request and will be applied in the order of their
|
|
appearance in the request.
|
|
|
|
* [Example "conn" request with three "via" stations]
|
|
(https://bahnapi.xyz/?type=conn&from=Bruck an der Mur&to=Salzburg&via=Leoben
|
|
&via=Selzthal&via=Linz)
|
|
|
|
### Search for current location of trains ("radar")
|
|
|
|
The following parameter is required for this type of request:
|
|
|
|
* "type": "radar"
|
|
|
|
The following optional parameter is accepted:
|
|
|
|
* "train": Train number (including prefix)
|
|
|
|
If "train" is not set, this will return the location and destination of all
|
|
trains currently running. If "train" is set, only trains matching the passed
|
|
train numbers are returned. Multiple "train" parameters may be passed in a
|
|
single request.
|
|
|
|
* [Example "radar" request](https://bahnapi.xyz/?type=radar&train=s9)
|
|
|
|
### 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, where the first value would be the station
|
|
of departure and the second value would be the station of arrival. 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)
|
|
|
|
This syntax is intended primarily for manual requests as additional sanity
|
|
checks for input data would be required to use it programatically.
|
|
Specifically, station names would not be allowed to include "/" and may not be
|
|
empty or contain only whitespace, as this will make it impossible to detect the
|
|
correct request type.
|
|
|
|
### 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)
|