Skip to content

A pure Python wrapper for the on-board APIs of many different transportation providers

License

Notifications You must be signed in to change notification settings

felix-zenk/onboardapis

Repository files navigation

onboardapis

Python versions PyPI version License
Build package Deploy documentation

Description

onboardapis allows you to interact with different on-board APIs. You can connect to the Wi-Fi of a supported transportation provider and access information about your journey, the vehicle you are travelling in and much more.

Note: The only vehicle type covered by this package currently is train. See the supported APIs for more information.


Installation

Install the latest stable version of onboardapis from PyPI using pip:

$ python -m pip install onboardapis

Version


Install the latest development version of onboardapis from GitHub using pip:

$ python -m pip install git+https://github.com/felix-zenk/onboardapis.git

Quickstart

To begin with development you will need to know a few things first:

  • What vehicle type you want to use
  • Who operates the vehicle
  • What country is the operator from

With this information you can get the needed module from the package onboardapis.<type>.<country>.<operator> and import the API class from it. For more specific information on finding the API you are looking for, see Finding your API.

Example: Let's say you want to use the on-board API called ICE Portal of Deutsche Bahn trains in Germany:

from onboardapis.train.de.db import ICEPortal

Every vehicle has an init-method that needs to be called to initialize the connection to the API. When using a vehicle as a context manager the init-method will automatically be called.

from onboardapis.train.de.db import ICEPortal
from onboardapis.units import kilometers, kilometers_per_hour

# init is automatically called
with ICEPortal() as train:
    print(
        f"Distance to {train.current_station.name}:",
        f"{kilometers(meters=train.calculate_distance(train.current_station)):.1f} km"
    )

# init has to be explicitly called
train = ICEPortal()
train.init()  # Explicit call to init method to initialize API connection

print(
    f"Travelling at {train.speed} m/s",
    f"({kilometers_per_hour(meters_per_second=train.speed):.2f} km/h)",
    f"with a delay of {train.delay.total_seconds():.0f} seconds"
)

And there you go!
You can read more information about available attributes in the onboardapis.train.Train and onboardapis.mixins documentation and the respective train's documentation.

Note: As you may have noticed by now, the package always returns datetime or timedelta objects for time based values and other values like distances, velocity, etc. in SI units, so you have to convert to other units if you want to use values different from the SI units. For convenience the onboardapis.units module provides functions to convert between units.

The name of a conversion function is the unit which will be the result of the conversion. Different units can be passed to a conversion function as keywords. Keywords can be combined to return the sum of the input units.


Documentation

GitHub-Pages

Access the documentation on GitHub-Pages.

Supported APIs

API API features Type Country Operator
RailnetRegio basic, geo train at (Austria) obb (Österreichische Bundesbahnen)
ICEPortal online, vehicle, geo, journey train de (Germany) db (Deutsche Bahn / DB AG)
FlixTainment basic, geo train de (Germany) flix (Flix Train GmbH)
MetronomCaptivePortal online train de (Germany) me (metronom Eisenbahngesellschaft mbH)

Experimental APIs

API API features Type Country Operator
PortalINOUI basic, vehicle, geo, journey train fr (France) sncf (SNCF Voyageurs)
RegioGuide / ZugPortal basic, vehicle, geo, journey train de (Germany) db (Deutsche Bahn / DB AG)
PortaleRegionale basic, basic-journey train it (Italy) ti (Trenitalia S.p.A.)
SBahnHannover online*, basic-journey train de (Germany) tdh (Transdev Hannover GmbH)
* Not supported yet.

APIs in development

API API features Type Country Operator
...

Finding your API

1. Determine vehicle type: train, plane, bus, ship, other.
2. Look up the ISO 3166-2 country code of the operators country
3. Operator code

The operator code is vehicle type specific. The following IDs are used:

Vehicle type Region Register
plane global ICAO
train europe VKM

Combine these three values to onboardapis.<type>.<country>.<operator>. This is the module that contains the API.

Hint: You can also get the module path by looking at Supported APIs / Experimental APIs and taking the three values from there.

API features

The API features define what information can be accessed through the API and is a general indicator of the API's capabilities.
Features can be combined.
The currently possible API features are:

  • basic / online: basic information is available such as connection status to the API. / The API supplies the user with internet access and the internet access can be enabled and disabled.
  • vehicle: The API supplies information about the vehicle such as the train ID, line number, etc.
  • geo: The API supplies information about the current location, speed, etc. of the vehicle.
  • basic-journey / journey: The API supplies basic journey information including the current station and the destination station. / The API supplies detailed journey information including all the stations and possibly connecting services.