| Name | onboardapis JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | None |
| Summary | A pure Python wrapper for the on-board APIs of many different transportation providers. |
| upload_time | 2024-06-27 13:52:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
public-transport
train
api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
onboardapis
===
[](https://pypi.org/project/onboardapis)
[](https://pypi.org/project/onboardapis)
[](https://github.com/felix-zenk/onboardapis/blob/main/LICENSE)
[](https://github.com/felix-zenk/onboardapis/actions/workflows/build.yml)
[](https://github.com/felix-zenk/onboardapis/actions/workflows/docs.yml)
> **Warning**: Version `2.0.0` introduces breaking changes! Existing code will definitely not work anymore.
## 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](#supported-apis) for more information.
---
## Installation
Install the latest stable version of onboardapis
from [PyPI](https://pypi.org/project/onboardapis)
using [pip](https://pip.pypa.io/en/stable/installation/):
```shell
$ python -m pip install onboardapis
```
[](https://pypi.org/project/onboardapis)
or the latest prerelease version of onboardapis
from [PyPI](https://pypi.org/project/onboardapis/2.0.0rc3/)
using [pip](https://pip.pypa.io/en/stable/installation/):
```shell
$ python -m pip install --pre onboardapis
```
[](https://pypi.org/project/onboardapis/2.0.0rc4/)
---
Install the latest development version of onboardapis
from [GitHub](https://github.com/felix-zenk/onboardapis)
using [pip](https://pip.pypa.io/en/stable/installation/):
```shell
$ 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](#find-your-api).
> **Example**: Let's say you want to use the on-board API called ICE Portal of Deutsche Bahn trains in Germany:
> ```python
> 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.
```python
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
[](https://felix-zenk.github.io/onboardapis/)
#### Access the documentation on [GitHub-Pages](https://felix-zenk.github.io/onboardapis/).
## Supported APIs
| API | [API features](#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](#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](#api-features) | Type | Country | Operator |
|------|-------------------------------|-------|---------|----------|
| ... | | | | |
## Find your API
##### 1. Determine vehicle type: ``train``, ``plane``, ``bus``, ``ship``, ``other``.
##### 2. Find the [ISO 3166-2 country code](https://en.wikipedia.org/wiki/ISO_3166-2#Current_codes) 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](https://en.wikipedia.org/wiki/List_of_airline_codes) |
| train | europe | [VKM](https://www.era.europa.eu/domains/registers/vkm_en) |
---
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](#supported-apis)
> / [Experimental 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "onboardapis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "public-transport, train, api",
"author": null,
"author_email": "Felix Zenk <felix.zenk@web.de>",
"download_url": "https://files.pythonhosted.org/packages/a8/eb/f8d720f5f2e112b43b1461883b0cc705c0208aa84a4d241547602501b44d/onboardapis-2.0.0.tar.gz",
"platform": null,
"description": "onboardapis\n===\n\n[](https://pypi.org/project/onboardapis)\n[](https://pypi.org/project/onboardapis)\n[](https://github.com/felix-zenk/onboardapis/blob/main/LICENSE) \n[](https://github.com/felix-zenk/onboardapis/actions/workflows/build.yml)\n[](https://github.com/felix-zenk/onboardapis/actions/workflows/docs.yml)\n\n> **Warning**: Version `2.0.0` introduces breaking changes! Existing code will definitely not work anymore.\n\n## Description\n\nonboardapis allows you to interact with different on-board APIs.\nYou can connect to the Wi-Fi of a supported transportation provider\nand access information about your journey, the vehicle you are travelling in and much more.\n\n> **Note:** The only vehicle type covered by this package currently is `train`.\n> See the [supported APIs](#supported-apis) for more information.\n\n---\n\n## Installation\n\nInstall the latest stable version of onboardapis\nfrom [PyPI](https://pypi.org/project/onboardapis)\nusing [pip](https://pip.pypa.io/en/stable/installation/):\n\n```shell\n$ python -m pip install onboardapis\n```\n\n[](https://pypi.org/project/onboardapis)\n\nor the latest prerelease version of onboardapis\nfrom [PyPI](https://pypi.org/project/onboardapis/2.0.0rc3/)\nusing [pip](https://pip.pypa.io/en/stable/installation/):\n\n```shell\n$ python -m pip install --pre onboardapis\n```\n\n[](https://pypi.org/project/onboardapis/2.0.0rc4/)\n\n---\n\nInstall the latest development version of onboardapis\nfrom [GitHub](https://github.com/felix-zenk/onboardapis)\nusing [pip](https://pip.pypa.io/en/stable/installation/):\n\n```shell\n$ python -m pip install git+https://github.com/felix-zenk/onboardapis.git\n```\n\n---\n\n## Quickstart\n\nTo begin with development you will need to know a few things first:\n\n* What vehicle type you want to use\n* Who operates the vehicle\n* What country is the operator from\n\nWith this information you can get the needed module from the package \n``onboardapis.<type>.<country>.<operator>`` and import the API class from it.\nFor more specific information on finding the API you are looking for,\nsee [Finding your API](#find-your-api).\n\n> **Example**: Let's say you want to use the on-board API called ICE Portal of Deutsche Bahn trains in Germany:\n> ```python\n> from onboardapis.train.de.db import ICEPortal\n> ```\n\nEvery vehicle has an ``init``-method that needs to be called to initialize the connection to the API.\nWhen using a vehicle as a context manager the ``init``-method will automatically be called.\n\n```python\nfrom onboardapis.train.de.db import ICEPortal\nfrom onboardapis.units import kilometers, kilometers_per_hour\n\n# init is automatically called\nwith ICEPortal() as train:\n print(\n f\"Distance to {train.current_station.name}:\",\n f\"{kilometers(meters=train.calculate_distance(train.current_station)):.1f} km\"\n )\n\n# init has to be explicitly called\ntrain = ICEPortal()\ntrain.init() # Explicit call to init method to initialize API connection\n\nprint(\n f\"Travelling at {train.speed} m/s\",\n f\"({kilometers_per_hour(meters_per_second=train.speed):.2f} km/h)\",\n f\"with a delay of {train.delay.total_seconds():.0f} seconds\"\n)\n```\n\nAnd there you go! \nYou can read more information about available attributes in the ``onboardapis.train.Train`` and ``onboardapis.mixins`` documentation\nand the respective train's documentation.\n\n> **Note**: As you may have noticed by now, the package always returns `datetime` or `timedelta` objects for time based values\n> and other values like distances, velocity, etc. in SI units,\n> so you have to convert to other units if you want to use values different from the SI units.\n> For convenience the ``onboardapis.units`` module provides functions to convert between units.\n>\n> The name of a conversion function is the unit which will be the result of the conversion.\n> Different units can be passed to a conversion function as keywords.\n> Keywords can be combined to return the sum of the input units.\n\n---\n\n## Documentation\n[](https://felix-zenk.github.io/onboardapis/)\n\n#### Access the documentation on [GitHub-Pages](https://felix-zenk.github.io/onboardapis/).\n\n\n## Supported APIs\n\n| API | [API features](#api-features) | Type | Country | Operator |\n|-----------------------|-------------------------------|-------|--------------|-----------------------------------------|\n| RailnetRegio | basic, geo | train | at (Austria) | obb (\u00d6sterreichische Bundesbahnen) |\n| ICEPortal | online, vehicle, geo, journey | train | de (Germany) | db (Deutsche Bahn / DB AG) |\n| FlixTainment | basic, geo | train | de (Germany) | flix (Flix Train GmbH) |\n| MetronomCaptivePortal | online | train | de (Germany) | me (metronom Eisenbahngesellschaft mbH) |\n\n## Experimental APIs\n\n| API | [API features](#api-features) | Type | Country | Operator |\n|------------------------|-------------------------------|-------|--------------|------------------------------|\n| PortalINOUI | basic, vehicle, geo, journey | train | fr (France) | sncf (SNCF Voyageurs) |\n| RegioGuide / ZugPortal | basic, vehicle, geo, journey | train | de (Germany) | db (Deutsche Bahn / DB AG) |\n| PortaleRegionale | basic, basic-journey | train | it (Italy) | ti (Trenitalia S.p.A.) |\n| SBahnHannover | *online*\\*, basic-journey | train | de (Germany) | tdh (Transdev Hannover GmbH) |\n\n * Not supported yet.\n\n## APIs in development\n\n| API | [API features](#api-features) | Type | Country | Operator |\n|------|-------------------------------|-------|---------|----------|\n| ... | | | | |\n\n## Find your API\n\n##### 1. Determine vehicle type: ``train``, ``plane``, ``bus``, ``ship``, ``other``.\n##### 2. Find the [ISO 3166-2 country code](https://en.wikipedia.org/wiki/ISO_3166-2#Current_codes) of the operators country\n##### 3. Operator code\n\nThe operator code is vehicle type specific. The following IDs are used:\n\n| Vehicle type | Region | Register |\n|--------------|--------|-------------------------------------------------------------|\n| plane | global | [ICAO](https://en.wikipedia.org/wiki/List_of_airline_codes) |\n| train | europe | [VKM](https://www.era.europa.eu/domains/registers/vkm_en) |\n\n---\n\nCombine these three values to `onboardapis.<type>.<country>.<operator>`.\nThis is the module that contains the API.\n\n> **Hint**: You can also get the module path by looking at [Supported APIs](#supported-apis)\n> / [Experimental APIs](#experimental-apis) and taking the three values from there.\n\n## API features\n\nThe API features define what information can be accessed through the API\nand is a general indicator of the API's capabilities. \nFeatures can be combined. \nThe currently possible API features are:\n- ``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.\n- ``vehicle``: The API supplies information about the vehicle such as the train ID, line number, etc.\n- ``geo``: The API supplies information about the current location, speed, etc. of the vehicle.\n- ``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.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A pure Python wrapper for the on-board APIs of many different transportation providers.",
"version": "2.0.0",
"project_urls": {
"Documentation": "https://felix-zenk.github.io/onboardapis/",
"Homepage": "https://felix-zenk.github.io/onboardapis",
"Issues": "https://github.com/felix-zenk/onboardapis/issues",
"Repository": "https://github.com/felix-zenk/onboardapis"
},
"split_keywords": [
"public-transport",
" train",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c28fb48ab694e2e3e2a64c19eea008994c4c1472d6c5629aa34d9945b64152c",
"md5": "dec47b7c4f4c307967177aa6f8298781",
"sha256": "a250adf521c6da0112d3dd1dda4a01cfa438b693d08e7c22ab640de339332096"
},
"downloads": -1,
"filename": "onboardapis-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dec47b7c4f4c307967177aa6f8298781",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 43552,
"upload_time": "2024-06-27T13:52:05",
"upload_time_iso_8601": "2024-06-27T13:52:05.162734Z",
"url": "https://files.pythonhosted.org/packages/0c/28/fb48ab694e2e3e2a64c19eea008994c4c1472d6c5629aa34d9945b64152c/onboardapis-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a8ebf8d720f5f2e112b43b1461883b0cc705c0208aa84a4d241547602501b44d",
"md5": "ab23b689ddb317256a0c22429e5a85bf",
"sha256": "d7b865c60df3e80b508e977a08993080e854f928b28dbbe8d851312d73f94492"
},
"downloads": -1,
"filename": "onboardapis-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ab23b689ddb317256a0c22429e5a85bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 33262,
"upload_time": "2024-06-27T13:52:07",
"upload_time_iso_8601": "2024-06-27T13:52:07.080008Z",
"url": "https://files.pythonhosted.org/packages/a8/eb/f8d720f5f2e112b43b1461883b0cc705c0208aa84a4d241547602501b44d/onboardapis-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-27 13:52:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "felix-zenk",
"github_project": "onboardapis",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "onboardapis"
}
