oebb_py/README.md

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)