{"id":26774625,"url":"https://github.com/plutokekz/mvg-api","last_synced_at":"2025-03-29T02:17:35.281Z","repository":{"id":176180779,"uuid":"573628061","full_name":"Plutokekz/MVG-Api","owner":"Plutokekz","description":"A Sync and Async Wrapper for the unofficial MVG Rest Api","archived":false,"fork":false,"pushed_at":"2024-07-18T13:39:49.000Z","size":310,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-07-18T17:06:54.992Z","etag":null,"topics":["api-wrapper","async","mvg","mvg-api","pydantic","pytest","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/async-mvg-api/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Plutokekz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-12-02T23:46:55.000Z","updated_at":"2024-07-18T13:39:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"d3143b8a-889e-4e53-8401-32afd1983f5e","html_url":"https://github.com/Plutokekz/MVG-Api","commit_stats":null,"previous_names":["plutokekz/mvg-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Plutokekz%2FMVG-Api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Plutokekz%2FMVG-Api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Plutokekz%2FMVG-Api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Plutokekz%2FMVG-Api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Plutokekz","download_url":"https://codeload.github.com/Plutokekz/MVG-Api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246126723,"owners_count":20727595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","async","mvg","mvg-api","pydantic","pytest","python"],"created_at":"2025-03-29T02:17:34.717Z","updated_at":"2025-03-29T02:17:35.267Z","avatar_url":"https://github.com/Plutokekz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unofficial MVG api\n\nAn async and sync wrapper for the MVG endpoints, with data validation over pydantic\n\n## Breaking Changes\n\nbetween version 0.1.5 and 0.2.0 the api has changed a lot. The api is now split into versions.\nThe old api is available under mvg_api.v1 and the new api is available under mvg_api.v2.\n\n## Features\n\n- Sync and async support: You can use this wrapper to make API calls synchronously or asynchronously based on your needs.\n  It provides flexibility and allows you to leverage the benefits of both approaches.\n\n- Pydantic schema validation: The wrapper integrates with Pydantic, \n a powerful data validation and parsing library, to validate API responses against\n predefined schemas. This ensures that the received data conforms to the expected structure\n and types. For every API endpoint, there is a corresponding Pydantic schema that defines the expected structure of the\n response. If the response does not match the schema, an exception is raised. **And you allways know what data you get**.\n\n## Installation\nInstall it over pip or from source by cloning the repository and installing \nthe dependencies with [poetry](https://python-poetry.org/).\n\n```bash\npip install async-mvg-api\n```\n\nor \n\n```bash\ngit clone https://github.com/Plutokekz/MVG-Api.git\ncd MVG-Api\npoetry install\n```\n## Usage\n\nWith the endpoint changes from MVG the api is now split into versions. Currently, there are two versions available.\nThe first version is the old api, which is still available and work, but I think in the future it may stop working \nand will be removed.\n\nThe second version is the new api, which is still in beta, should work until MVG changes there endpoints one again. \n### Example with the v2 api\n\n#### Sync\n```python\nfrom mvg_api.v2.mvg import SyncMVG\nmvg = SyncMVG()\nlocation = mvg.get_location(\"Hauptbahnhof\")\n```\n#### Async\n```python\nfrom mvg_api.v2.mvg import AsyncMVG\nimport asyncio\nmvg = AsyncMVG()\nlocation = asyncio.run(mvg.get_location(\"Hauptbahnhof\"))\n```\n\nthe location from sync and async should look somthing like this:\n\n```python\nLocationList(\n    locations=[\n        Location(\n            globalId='de:09162:6',\n            type=\u003cLocationType.STATION: 'STATION'\u003e,\n            latitude=48.14003,\n            longitude=11.56107,\n            divaId=6,\n            place='München',\n            name='Hauptbahnhof',\n            hasZoomData=True,\n            tariffZones='m',\n            aliases='Hbf München main station central station Muenchen Munchen HU HO HUHO',\n            transportTypes=[\n                'UBAHN',\n                'TRAM',\n                'SBAHN'\n                ],\n            surroundingPlanLink='HU'\n            ),\n            ...\n        ]\n    )\n```\n\n### Example with the v1 api\n\n#### Sync\n```python\nfrom mvg_api.v1.mvg import MVG\nmvg = MVG()\nlocation = mvg.get_location(\"Hauptbahnhof\")\n```\n#### Async\n```python\nfrom mvg_api.v1.mvg import AsyncMVG\nimport asyncio\nmvg = AsyncMVG()\nlocation = asyncio.run(mvg.get_location(\"Hauptbahnhof\"))\n```\n\nthe location from sync and async should look somthing like this:\n\n```python\nLocationList(\n    locations=[\n        Location(\n            globalId='de:09162:6',\n            type=\u003cLocationType.STATION: 'STATION'\u003e,\n            latitude=48.14003,\n            longitude=11.56107,\n            divaId=6,\n            place='München',\n            name='Hauptbahnhof',\n            hasZoomData=True,\n            tariffZones='m',\n            aliases='Hbf München main station central station Muenchen Munchen HU HO HUHO',\n            transportTypes=[\n                'UBAHN',\n                'TRAM',\n                'SBAHN'\n                ],\n            surroundingPlanLink='HU'\n            ),\n            ...\n        ]\n    )\n```\n\n## Documentation of v2 endpoints\n### Endpoints\n\n#### Method: get_departures_by_name\n\n```python\ndef get_departures_by_name(self, name: str, **kwargs) -\u003e departure.Departures\n```\n\nGet the departures for a given station name, the keyword arguments are the same as in get_departures\n\n- Parameters:\n    - `name`: Name of the Station.\n    - `**kwargs`: Keyword arguments for the get_departures method.\n- Returns a `departure.Departures` object representing the Departures information.\n\n#### Method: get_connection_by_name\n\n````python\ndef get_connection_by_name(self, start: str, stop: str, start_datetime: Optional[datetime.datetime] = None,\n                           date_time_is_arrival: bool = False, **kwargs) -\u003e Connections:\n````\n\nGet a connection between two locations by the station or address name, the keyword arguments are the same as in\nget_connection\n\n- Parameters:\n    - `start`: the start location/ address name\n    - `stop`: the stop location/ address name\n    - `start_datetime`: the start datetime of the connection\n    - `date_time_is_arrival`: if the start_datetime is the arrival time\n    - `**kwargs`: Keyword arguments for the get_connection method.\n- Returns a `connection.Connections` object representing the connection information.\n\n#### Method: get_ticker\n\n```python\ndef get_ticker(self) -\u003e ems.Messages\n```\nGet ticker messages, updates about the disruptions and planed works on the MVG train network \nThere 2 types of messages DISRUPTION and PLANNED\n- Returns a list of ticker messages containing updates about disruptions and planned works on the MVG train network.\n\n#### Method: get_station\n\n```python\ndef get_station(self, station_id: str) -\u003e station.Station\n```\n\nGet a station by its id the Station id can be found in the get_all_stations list, or it can be obtained from a\nlocation method wenn the found Location is of the type STATION\n\n- Parameters:\n  - `station_id`: The ID of the station.\n- Returns a `station.Station` object representing the station information.\n\n#### Method: get_departures\n\n```python\ndef get_departures(\n    self,\n    station_id: str,\n    *,\n    limit: Optional[int] = None,\n    offset_minutes: Optional[int] = None,\n    transport_types: Optional[Any] = None,\n    language: Optional[str] = None,\n) -\u003e departure.Departures\n```\nGet the departures for a station\n- Parameters:\n  - `station_id`: the same id as in get_station, for example de:09162:6 for Hauptbahnhof, and it can be\n        obtained\n        from a location method wenn the found Location is of the type STATION or from the get_all_stations method\n  - `limit` (optional): The maximum number of departures to return.\n  - `offset_minutes` (optional): The offset in minutes from the current time for the departures.\n  - `transport_types` (optional): A list of specific transport types to filter the departures (e.g., UBAHN, TRAM, BUS).\n  - `language` (optional): the language ? I have no idea why this is here maybe for the language in the response. But I\n        didn't see any difference when I changed it\n- Returns a `departure.Departures` object representing the list of departures.\n\n#### Method: get_escalators_and_elevators\n\n```python\ndef get_escalators_and_elevators(self, efa_id: int) -\u003e transportdevice.StationTransportDevices\n```\nGet the escalators and elevators location and status for a station\n- Parameters:\n  - `efa_id`: an integer number that is associated with a station. It is included in the Station object but\n        under the name of divId for some reason.\n- Returns a `transportdevice.StationTransportDevices` object representing the escalators and elevators at the station.\n\n#### Method: get_aushang\n\n```python\ndef get_aushang(self, plan_id: str) -\u003e aushang.Aushaenge\n```\nGet the aushang for a station, get all Playn that a currently active in a stations blackboard.\n- Parameters:\n  - `plan_id`: I am not sure bit it seems to be the first 2 letters of the station name in uppercase.\n         For example KA for Karlsplatz\n- Returns a `aushang.Aushaenge` object representing the aushang (playn) currently active at the station.\n\n#### Method: get_station_ids\n\n```python\ndef get_station_ids(self) -\u003e List[str]\n```\nGet all the station ids\n- Returns a list of all station IDs available.\n\n#### Method: get_location\n\n```python\ndef get_location(\n    self,\n    query: str,\n    limit_address_poi: Optional[int] = None,\n    limit_stations: Optional[int] = None,\n    location_types: Optional[List[LocationType]] = None,\n) -\u003e location.Locations\n```\nGet the location of a query, it can be a station name or a street name or a POI\n- Parameters:\n  - `query`: The address, station name, or POI name to search for.\n  - `limit_address_poi` (optional): Limit the number of addresses or POIs to return.\n  - `limit_stations` (optional): Limit the number of stations to return.\n  - `location_types` (optional): Limit the location types to return (e.g., STATION, POI, ADDRESS).\n- Returns a `location.Locations` object representing the list of locations.\n\n#### Method: get_messages\n\n```python\ndef get_messages(self, message_type: Optional[str] = None) -\u003e messages.Messages\n```\nGet the messages from the message board. Somehow similar to the ems ticker but it has more and different\ninformation.\n\n- Parameters:\n  - `message_type` (optional): The type of message to retrieve (e.g., INCIDENT, SCHEDULE_CHANGE).\n- Returns a `messages.Messages` object representing the list of messages from the message board.\n\n#### Method: get_connection\n\n```python\ndef get_connection(\n    self,\n    origin_station_id: str,\n    destination_station_id: str,\n    routing_date_time: str,\n    *,\n    routing_date_time_is_arrival: bool,\n    transport_types: Optional[str] = None,\n    origin_latitude: Optional[float] = None,\n    origin_longitude: Optional[float] = None,\n    destination_latitude: Optional[float] = None,\n    destination_longitude: Optional[float] = None,\n) -\u003e connection.Connections\n```\nGet the connections between two stations or coordinates.\nYou can use either station_id to station_id or coordinates to coordinates or station_id to coordinates.\n- Parameters:\n  - `origin_station_id`: The ID of the origin station.\n  - `destination_station_id`: The ID of the destination station.\n  - `routing_date_time`: The date and time of the departure or arrival.\n  - `routing_date_time_is_arrival`: Specifies if `routing_date_time` is the arrival time.\n  - `transport_types` (optional): the transport types to use, available types are SCHIFF,RUFTAXI,BAHN,UBAHN,TRAM,SBAHN,BUS\n        ,REGIONAL_BUS\n  - `origin_latitude` (optional): The latitude of the origin station.\n  - `origin_longitude` (optional): The longitude of the origin station.\n  - `destination_latitude` (optional): The latitude of the destination station.\n  - `destination_longitude` (optional): The longitude of the destination station.\n- Returns a `connection.Connections` object representing the list of connections between the origin and destination.\n\n#### Method: get_lineinfo\n\n```python\ndef get_lineinfo(self, language: Optional[str]) -\u003e lineinfo.Infos\n```\nGet the line info for some wired special lines like \"lufthanse express bus\"\n- Parameters:\n  - `language` (optional):  here the language argument also makes no difference in the response output.\n- Returns a `lineinfo.Infos` object representing the line information for special lines.\n\n#### Method: get_stations\n\n```python\ndef get_stations(\n    self, hash_: Optional[str] = None, world: Optional[bool] = None\n) -\u003e stations.Locations\n```\nGet all the stations, like get_station_ids but with the hole station information.\n- Parameters:\n  - `hash_` (optional):I don't know for what this hash is. (In the response is a hash, but if you send it again you get\n        no response, so keep it empty)\n  - `world` (optional): you can set the world to true or false. Maybe some day the MVG is operating worldwide.\n- Returns a `stations.Locations` object representing the list of stations.\n\n#### Method: get_lines\n\n```python\ndef get_lines(self) -\u003e line.Lines\n```\nGet all the lines\n- Returns a `line.Lines` object representing the list of lines.\n\n#### Method: get_zoom_station\n\n```python\ndef get_zoom_station(self, div_id: int) -\u003e zoom_station.ZoomStation\n```\nGet information about the availability TransportDevices at a station. Like elevators, escalators, etc.\nThe information if similar to the information you get from the get_escalators_and_elevators\n- Parameters:\n  - `div_id`: An internal number associated with a station.\n- Returns a `zoom_station.ZoomStation` object representing information about the availability of transport devices at a station.\n\n#### Method: get_plan\n\n```python\ndef get_plan(self, div_id: int) -\u003e bytes\n```\nGet the plan of a station. The response is a pdf file in bytes.\n- Parameters:\n  - `div_id`: An internal number associated with a station.\n- Returns the plan of a station as a byte array (PDF format).\n\n#### Method: get_zoom_station_out_of_order\n\n```python\ndef get_zoom_station_out_of_order(self, div_id: int) -\u003e out_of_order.StationOutOfOrder\n```\nGet the information about the availability of TransportDevices at a station. Like elevators, escalators, etc.\n- Parameters:\n  - `div_id`: An internal number associated with a station.\n- Returns a `out_of_order.StationOutOfOrder\n\nobject representing the information about the availability of transport devices at a station.\n\n#### Method: get_vehicles_in_bounding_box\n\n```python\ndef get_vehicles_in_bounding_box(\n    self, bbswlat: float, bbswlng: float, bbnelat: float, bbnelng: float\n) -\u003e vehicel.VehiclesAndSharingStations\n```\nGet the vehicles and sharing stations in a bounding box. The bounding box is defined by two coordinates.\n- Parameters:\n  - `bbswlat`: The latitude of the bounding box's southwest corner.\n  - `bbswlng`: The longitude of the bounding box's southwest corner.\n  - `bbnelat`: The latitude of the bounding box's northeast corner.\n  - `bbnelng`: The longitude of the bounding box's northeast corner.\n- Returns a `vehicel.VehiclesAndSharingStations` object representing the vehicles and sharing stations within the specified bounding box.\n\n#### Method: get_surrounding_plan\n\n```python\ndef get_surrounding_plan(\n    self, plan_id: str, world: bool = True, include_image_data: bool = True\n) -\u003e surounding_plans.Plan\n```\nGet the surrounding plan of a station. If you include the image data you get a base64 encoded pdf of the plan.\n        So you have to decode it first.\n- Parameters:\n  - `plan_id`: the first 2 letters of the station name in uppercase. For example \"KA\" for Karlsplatz\n  - `world` (optional): again a world argument, but it makes no difference in the response output.\n  - `include_image_data` (optional): A boolean value specifying if the response should include the image data of the plan.\n- Returns a `surounding_plans.Plan` object representing the surrounding plan of a station.\n\n#### Method: get_surrounding_plans\n\n```python\ndef get_surrounding_plans(self, world: Optional[bool] = True) -\u003e surounding_plans.Plans\n```\nGet the surrounding plan of a station. If you include the image data you get a base64 encoded pdf of the plan.\nSo you have to decode it first.\n- Parameters:\n  - `world` (optional): again a world argument, but it makes no difference in the response output.\n- Returns a `surounding_plans.Plans` object representing the list of surrounding plans for all stations.\n\n\n## Tests\n\n```bash\npoetry run pytest mvg_api/v1/tests/api_tests.py mvg_api/v2/tests/api_tests.py\n```\n\n# Credit\nFor Endpoint Information and Code snippets\n* https://github.com/leftshift/python_mvg_api\n* https://www.mvg.de/\n\n# Usage policy of the MVG api\n## ACHTUNG:\nUnsere Systeme dienen der direkten Kundeninteraktion. Die Verarbeitung unserer Inhalte oder Daten durch Dritte erfordert unsere ausdrückliche Zustimmung. Für private, nicht-kommerzielle Zwecke, wird eine gemäßigte Nutzung ohne unsere ausdrückliche Zustimmung geduldet. Jegliche Form von Data-Mining stellt keine gemäßigte Nutzung dar. Wir behalten uns vor, die Duldung grundsätzlich oder in Einzelfällen zu widerrufen. Fragen richten Sie bitte gerne an: redaktion@mvg.de.\n\nIn other words: Private, noncommercial, moderate use of the API is tolerated.\nThey do not consider data mining as a moderate use.\n\n(Disclaimer: I am not a lawyer, this is not legal advice)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplutokekz%2Fmvg-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplutokekz%2Fmvg-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplutokekz%2Fmvg-api/lists"}