| Name | mvg JSON |
| Version |
1.1.2
JSON |
| download |
| home_page | |
| Summary | An unofficial interface to timetable information of the Münchner Verkehrsgesellschaft (MVG). |
| upload_time | 2023-08-27 14:32:17 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mvg
This package aims to provide a clean, performant and barrier-free interface to timetable information of the *Münchner Verkehrsgesellschaft* (MVG), responsible for public transport in Munich. It exports the class `MvgApi` to retrieve stations, lines and departures from the unofficial JSON API at https://www.mvg.de.
## Disclaimer
This project is **not an official project from the Münchner Verkehrsgesellschaft (MVG)**. It was developed as a private project from lack of a documented and openly accessible API. It simply reproduces the requests made by https://www.mvg.de to provide a barrier-free access to local timetable information.
Therefore, the following **usage restrictions from the MVG Imprint do apply to all users of this package**:
> Our systems are used for direct customer interaction. The processing of our content or data by third parties requires our express consent. For **private, non-commercial purposes, moderate use is tolerated** without our explicit consent. Any form of **data mining does not constitute moderate use**. We reserve the right to revoke this permission in principle or in individual cases. Please direct any questions to: redaktion@mvg.de
>
> (from https://www.mvg.de/impressum.html, accessed on 04. Feb 2023)
## Why another MVG package?
The project was inspired by two existing packages:
- The package [PyMVGLive](https://pypi.org/project/PyMVGLive) from 2017 does provide an interface to the former MVGLive API at `mvg-live.de`. As of 2022 the MVGLive website does not exist anymore and the package has been archived. Although the old API still works for some stations, it does not for others - mainly due to updated station identifiers. Therefore, the package is considered deprecated and cannot be used for new designs.
- The newer package [mvg-api](https://pypi.org/project/mvg-api) offers an implementation from 2020 based on the API at `www.mvg.de/api/fahrinfo`. It considers the updated station identifiers and still works perfectly. This package provides the basis for recent projects such as [mvg-cli](https://pypi.org/project/mvg-cli).
So why another MVG API package? In the end three reasons were decisive:
- The recent website at uses a new API at `www.mvg.de/api/fib/v2`, which seems to be more performant than the previous one.
- None of the existing packages offer asynchronous calls for concurrent code projects.
- An optimized package was required to develop a [Home Assistant](https://www.home-assistant.io) integration.
## Installation
Install from the Python Package Index (PyPI) using `pip`:
```
pip install mvg
```
## Basic Usage
The interface was designed to be simple and intuitive. Basic usage follows these steps:
- Find a station using `MvgApi.station(station)` by its name and place (e.g. `"Universität, München"`) or its global station identifier (e.g. `"de:09162:70"`).
- Alternatively, `MvgApi.nearby(latitude, longitude)` finds the nearest station.
- Create an API instance using `MvgApi(station)` by station name and place or its global identifier.
- Use the method `.departures()` to retrieve information from the API.
A basic example looks like this:
```python
from mvg import MvgApi
station = MvgApi.station('Universität, München')
if station:
mvgapi = MvgApi(station['id'])
departures = mvgapi.departures()
print(station, departures)
```
### Available Stations and Lines
The static methods `MvgApi.stations()` and `MvgApi.lines()` expose a list of all available stations and a list of all available lines from designated API endpoints. While these calls are great for reference, they are also quite extensive and should not be used within a frequent query loop.
### Filters
The results from `.departures(limit, offset, transport_types)` can be filtered using the following arguments:
- `limit` limits the output to the given number of departures, defaults to 10
- `offset` adds an offset (e.g. walking distance to the station) in minutes, defaults to 0
- `transport_types` filters the result by a list of transport types (e.g. `[TransportType.UBAHN]`)
A filtered example looks like this:
```python
from mvg import MvgApi, TransportType
station = MvgApi.station('Universität, München')
if station:
mvgapi = MvgApi(station['id'])
departures = mvgapi.departures(
limit=3,
offset=5,
transport_types=[TransportType.UBAHN])
print(station, departures)
```
### Example results
`station()` or `nearby()` results a `dict`:
```
{
'id': 'de:09162:70',
'name': 'Universität',
'place': 'München'
'latitude': 48.15007,
'longitude': 11.581
}
```
`departures()` results a `list` of `dict`:
```
[{
'time': 1668524580,
'planned': 1668524460,
'line': 'U3',
'destination': 'Fürstenried West',
'type': 'U-Bahn',
'icon': 'mdi:subway',
'cancelled': False,
'messages': []
}, ... ]
```
## Advanced Usage: Asynchronous Methods
The class `MvgApi` internally calls asynchronous methods using `asyncio` and `aiohttp` to perform the web requests efficiently. These asynchronous methods are marked by the suffix `_async` and can be utilized by users in projects with concurrent code.
The basic example but with asynchronous calls looks like this:
```python
import asyncio
from mvg import MvgApi
async def demo() -> None:
station = await MvgApi.station_async('Universität, München')
if station:
departures = MvgApi.departures_async(station['id'])
print(station, await departures)
loop = asyncio.get_event_loop()
loop.run_until_complete(demo())
```
Raw data
{
"_id": null,
"home_page": "",
"name": "mvg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Martin Dziura <m.dziura@tum.de>",
"download_url": "https://files.pythonhosted.org/packages/f1/80/2521160c266fd4cbfa0d17c8de1a563547560ca95810b7a24fffa23039b1/mvg-1.1.2.tar.gz",
"platform": null,
"description": "# mvg\n\nThis package aims to provide a clean, performant and barrier-free interface to timetable information of the *M\u00fcnchner Verkehrsgesellschaft* (MVG), responsible for public transport in Munich. It exports the class `MvgApi` to retrieve stations, lines and departures from the unofficial JSON API at https://www.mvg.de.\n\n## Disclaimer\n\nThis project is **not an official project from the M\u00fcnchner Verkehrsgesellschaft (MVG)**. It was developed as a private project from lack of a documented and openly accessible API. It simply reproduces the requests made by https://www.mvg.de to provide a barrier-free access to local timetable information.\n\nTherefore, the following **usage restrictions from the MVG Imprint do apply to all users of this package**:\n\n> Our systems are used for direct customer interaction. The processing of our content or data by third parties requires our express consent. For **private, non-commercial purposes, moderate use is tolerated** without our explicit consent. Any form of **data mining does not constitute moderate use**. We reserve the right to revoke this permission in principle or in individual cases. Please direct any questions to: redaktion@mvg.de\n> \n> (from https://www.mvg.de/impressum.html, accessed on 04. Feb 2023)\n\n## Why another MVG package?\n\nThe project was inspired by two existing packages:\n- The package [PyMVGLive](https://pypi.org/project/PyMVGLive) from 2017 does provide an interface to the former MVGLive API at `mvg-live.de`. As of 2022 the MVGLive website does not exist anymore and the package has been archived. Although the old API still works for some stations, it does not for others - mainly due to updated station identifiers. Therefore, the package is considered deprecated and cannot be used for new designs.\n- The newer package [mvg-api](https://pypi.org/project/mvg-api) offers an implementation from 2020 based on the API at `www.mvg.de/api/fahrinfo`. It considers the updated station identifiers and still works perfectly. This package provides the basis for recent projects such as [mvg-cli](https://pypi.org/project/mvg-cli).\n\nSo why another MVG API package? In the end three reasons were decisive:\n- The recent website at uses a new API at `www.mvg.de/api/fib/v2`, which seems to be more performant than the previous one.\n- None of the existing packages offer asynchronous calls for concurrent code projects.\n- An optimized package was required to develop a [Home Assistant](https://www.home-assistant.io) integration.\n\n## Installation\n\nInstall from the Python Package Index (PyPI) using `pip`:\n```\npip install mvg\n```\n\n## Basic Usage\n\nThe interface was designed to be simple and intuitive. Basic usage follows these steps:\n- Find a station using `MvgApi.station(station)` by its name and place (e.g. `\"Universit\u00e4t, M\u00fcnchen\"`) or its global station identifier (e.g. `\"de:09162:70\"`).\n- Alternatively, `MvgApi.nearby(latitude, longitude)` finds the nearest station.\n- Create an API instance using `MvgApi(station)` by station name and place or its global identifier.\n- Use the method `.departures()` to retrieve information from the API.\n\nA basic example looks like this:\n\n```python\nfrom mvg import MvgApi\n\nstation = MvgApi.station('Universit\u00e4t, M\u00fcnchen')\nif station:\n mvgapi = MvgApi(station['id'])\n departures = mvgapi.departures()\n print(station, departures)\n```\n\n### Available Stations and Lines\n\nThe static methods `MvgApi.stations()` and `MvgApi.lines()` expose a list of all available stations and a list of all available lines from designated API endpoints. While these calls are great for reference, they are also quite extensive and should not be used within a frequent query loop.\n\n### Filters\n\nThe results from `.departures(limit, offset, transport_types)` can be filtered using the following arguments:\n\n- `limit` limits the output to the given number of departures, defaults to 10\n- `offset` adds an offset (e.g. walking distance to the station) in minutes, defaults to 0\n- `transport_types` filters the result by a list of transport types (e.g. `[TransportType.UBAHN]`)\n\nA filtered example looks like this:\n\n```python\nfrom mvg import MvgApi, TransportType\n\nstation = MvgApi.station('Universit\u00e4t, M\u00fcnchen')\nif station:\n mvgapi = MvgApi(station['id'])\n departures = mvgapi.departures(\n limit=3,\n offset=5,\n transport_types=[TransportType.UBAHN])\n print(station, departures)\n```\n\n### Example results\n\n`station()` or `nearby()` results a `dict`:\n```\n{ \n'id': 'de:09162:70', \n'name': 'Universit\u00e4t', \n'place': 'M\u00fcnchen'\n'latitude': 48.15007, \n'longitude': 11.581\n}\n```\n`departures()` results a `list` of `dict`:\n```\n[{\n'time': 1668524580,\n'planned': 1668524460,\n'line': 'U3',\n'destination': 'F\u00fcrstenried West',\n'type': 'U-Bahn',\n'icon': 'mdi:subway',\n'cancelled': False,\n'messages': []\n}, ... ]\n```\n\n## Advanced Usage: Asynchronous Methods\n\nThe class `MvgApi` internally calls asynchronous methods using `asyncio` and `aiohttp` to perform the web requests efficiently. These asynchronous methods are marked by the suffix `_async` and can be utilized by users in projects with concurrent code.\n\nThe basic example but with asynchronous calls looks like this:\n\n```python\nimport asyncio\nfrom mvg import MvgApi\n\nasync def demo() -> None:\n station = await MvgApi.station_async('Universit\u00e4t, M\u00fcnchen')\n if station:\n departures = MvgApi.departures_async(station['id'])\n print(station, await departures)\nloop = asyncio.get_event_loop()\nloop.run_until_complete(demo())\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "An unofficial interface to timetable information of the M\u00fcnchner Verkehrsgesellschaft (MVG).",
"version": "1.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/mondbaron/mvg/issues",
"Documentation": "https://mondbaron.github.io/mvg",
"Source": "https://github.com/mondbaron/mvg"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ccee7e920e423dc184e2371be44e1a4915665b1de952acdd58605deb0b06934b",
"md5": "6bd78ef46f961645652d009713f4901f",
"sha256": "285357713caeaa81d0644b0439378299e0cee78678f50e5036df5d50072220fc"
},
"downloads": -1,
"filename": "mvg-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6bd78ef46f961645652d009713f4901f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8110,
"upload_time": "2023-08-27T14:32:15",
"upload_time_iso_8601": "2023-08-27T14:32:15.539775Z",
"url": "https://files.pythonhosted.org/packages/cc/ee/7e920e423dc184e2371be44e1a4915665b1de952acdd58605deb0b06934b/mvg-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f1802521160c266fd4cbfa0d17c8de1a563547560ca95810b7a24fffa23039b1",
"md5": "4144cbdbab02f46e6a33aef5f04448c2",
"sha256": "c78309a9afdd755e0ef464287e7bb7ca3ad3dea444ecc03fce5ffc3983bf9e78"
},
"downloads": -1,
"filename": "mvg-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "4144cbdbab02f46e6a33aef5f04448c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10764,
"upload_time": "2023-08-27T14:32:17",
"upload_time_iso_8601": "2023-08-27T14:32:17.359461Z",
"url": "https://files.pythonhosted.org/packages/f1/80/2521160c266fd4cbfa0d17c8de1a563547560ca95810b7a24fffa23039b1/mvg-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-27 14:32:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mondbaron",
"github_project": "mvg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mvg"
}
