aschuma / vvs_direct_connect

A Docker-based REST service that offers real-time departure information for a dedicated VVS connection of the local public transport system in Stuttgart

VVS Direct Connect REST Service

Simple REST service providing connection data for a dedicated VVS connection. VVS is the local public transport in Stuttgart.

The REST endpoints /api/v1/ and / (this is an alias for /api/v1/) exclusively handle direct connections. Additionally, the /api/v2/ endpoint supports interchange stations.

Start Server

$ docker run --rm -p15151:15151 -ti \
   -e VVS_FROM=de:08111:6118 \
   -e VVS_TO=de:08116:7800 \
   aschuma/vvs_direct_connect:latest

----- VVS Direct Connect -----------------------------------
Copyright (c) 2021-2024 aschuma (https://github.com/aschuma)
------------------------------------------------------------

Settings:
	- VVS_FROM=de:08111:6118
	- VVS_TO=de:08116:7800
	- VVS_LIMIT=10
	- VVS_TIME_OFFSET_MINUTES=12

Supported platforms:

• linux/amd64
• linux/arm64
• linux/arm/v7 (PI 4B)

Call Rest Endpoint

⚠️ Kindly note that the default port has been updated to 15151.

$ curl 127.0.0.1:15151/api/v2/

{
  "status": 200,
  "trips": [
    {
      "arrival_delay": 0,
      "arrival_estimated": "2024-04-02T09:14:00Z",
      "arrival_planed": "2024-04-02T09:14:00Z",
      "departure_delay": 0,
      "departure_estimated": "2024-04-02T09:03:00Z",
      "departure_planned": "2024-04-02T09:03:00Z",
      "details": [
        {
          "arrival_estimated": "2024-04-02T09:14:00Z",
          "arrival_planed": "2024-04-02T09:14:00Z",
          "departure_estimated": "2024-04-02T09:03:00Z",
          "departure_planed": "2024-04-02T09:03:00Z",
          "from": "Stuttgart Hauptbahnhof (oben)",
          "from_id": "de:08111:6115:6:12",
          "number": "MEX16",
          "to": "Esslingen (N)",
          "to_id": "de:08116:7800:2:5"
        }
      ],
      "from": "Stuttgart Hauptbahnhof (oben)",
      "from_id": "de:08111:6115:6:12",
      "number": "MEX16",
      "numbers": [
        "MEX16"
      ],
      "to": "Esslingen (N)",
      "to_id": "de:08116:7800:2:5",
      "travel_time": 11
    },
    {
      "arrival_delay": 0,
      "arrival_estimated": "2024-04-02T09:27:00Z",
      "arrival_planed": "2024-04-02T09:27:00Z",
      "departure_delay": 1,
      "departure_estimated": "2024-04-02T09:11:00Z",
      "departure_planned": "2024-04-02T09:10:00Z",
      "details": [
        {
          "arrival_estimated": "2024-04-02T09:27:00Z",
          "arrival_planed": "2024-04-02T09:27:00Z",
          "departure_estimated": "2024-04-02T09:11:00Z",
          "departure_planed": "2024-04-02T09:10:00Z",
          "from": "Stuttgart Hauptbahnhof (tief)",
          "from_id": "de:08111:6118:1:102",
          "number": "S1",
          "to": "Esslingen (N)",
          "to_id": "de:08116:7800:1:8"
        }
      ],
      "from": "Stuttgart Hauptbahnhof (tief)",
      "from_id": "de:08111:6118:1:102",
      "number": "S1",
      "numbers": [
        "S1"
      ],
      "to": "Esslingen (N)",
      "to_id": "de:08116:7800:1:8",
      "travel_time": 17
    },
    {
      "arrival_delay": 0,
      "arrival_estimated": "2024-04-02T09:42:00Z",
      "arrival_planed": "2024-04-02T09:42:00Z",
      "departure_delay": 1,
      "departure_estimated": "2024-04-02T09:26:00Z",
      "departure_planned": "2024-04-02T09:25:00Z",
      "details": [
        {
          "arrival_estimated": "2024-04-02T09:42:00Z",
          "arrival_planed": "2024-04-02T09:42:00Z",
          "departure_estimated": "2024-04-02T09:26:00Z",
          "departure_planed": "2024-04-02T09:25:00Z",
          "from": "Stuttgart Hauptbahnhof (tief)",
          "from_id": "de:08111:6118:1:102",
          "number": "S1",
          "to": "Esslingen (N)",
          "to_id": "de:08116:7800:1:8"
        }
      ],
      "from": "Stuttgart Hauptbahnhof (tief)",
      "from_id": "de:08111:6118:1:102",
      "number": "S1",
      "numbers": [
        "S1"
      ],
      "to": "Esslingen (N)",
      "to_id": "de:08116:7800:1:8",
      "travel_time": 17
    },
    {
      "arrival_delay": 0,
      "arrival_estimated": "2024-04-02T09:48:00Z",
      "arrival_planed": "2024-04-02T09:48:00Z",
      "departure_delay": 0,
      "departure_estimated": "2024-04-02T09:39:00Z",
      "departure_planned": "2024-04-02T09:39:00Z",
      "details": [
        {
          "arrival_estimated": "2024-04-02T09:48:00Z",
          "arrival_planed": "2024-04-02T09:48:00Z",
          "departure_estimated": "2024-04-02T09:39:00Z",
          "departure_planed": "2024-04-02T09:39:00Z",
          "from": "Stuttgart Hauptbahnhof (oben)",
          "from_id": "de:08111:6115:8:15",
          "number": "RE5",
          "to": "Esslingen (N)",
          "to_id": "de:08116:7800:2:5"
        }
      ],
      "from": "Stuttgart Hauptbahnhof (oben)",
      "from_id": "de:08111:6115:8:15",
      "number": "RE5",
      "numbers": [
        "RE5"
      ],
      "to": "Esslingen (N)",
      "to_id": "de:08116:7800:2:5",
      "travel_time": 9
    }
  ]
}

Parameter

• VVS_FROM departure station id
• VVS_TO destination station id
• VVS_LIMIT max number of trips to fetch
• VVS_TIME_OFFSET_MINUTES walking distance to departure station

Obtaining the Station IDs

Please consult https://www.openvvs.de/dataset/haltestellen to identify the origin and destination stations.

Alternatively, you can use the online timetable information to get the IDs. To do so, open VVS https://www3.vvs.de/ in your browser. Enter origin and destination stations and click submit, e.g. origin=Stuttgart and destination=Esslingen:

Copy the Browser URL into a text editor:

Search for the origand destparameters and the associated values. In this case de:08111:6118 is the ID of the origin station (Stuttgart). The ID of the destination station (Esslingen) is de:08116:7800.

Address Support - Obtaining the Street IDs

The REST endpoint /api/v2 additionally provides also some support for addresses within the VVS area. The format for the address Konrad Adenauer Str 32 (Staatsgalerie) is as follows: streetID:1500001775:32:8111000:51:Konrad-Adenauer-Straße:Stuttgart:Konrad-Adenauer-Straße::Konrad-Adenauer-Straße:70173:ANY:DIVA_SINGLEHOUSE:3513826:755185:NBWT:VVS:0.

You can also obtain the corresponding value through a VVS query as described above.

Credits

Credits to Yannick for vvspy

Further Information

• https://www.openvvs.de/
• https://www.openvvs.de/dataset/haltestellen
• https://www.vdv.de/ip-kom-oev.aspx
• https://github.com/VDVde/TRIAS

vvs_direct_connect's Issues

Update GH Workflows

vvspy readme notice

Hey @aschuma

cooles Projekt!
Hättest du was dagegen, dass ich es auf dem Readme von vvspy erwähne?

Transfer Mode Support

The application currently only supports direct connections between two VVS train stations.

The requirement now is to also support connections with transfers. This new behavior should be switchable via a feature flag, thus keeping the existing functionality untouched.

Furthermore, addresses within the VVS area should be supported as origins and destinations. If pedestrian paths are included, they should be filtered out. In the case of necessary transfers, only the first S-Bahn or tram line (referred to as "transportation_number") should be returned in the existing field. In a separate new structure, the intermediate stations and lines will be returned.

Note
The format of addresses such as "Konrad Adenauer Str 32 (Staatsgalerie)" looks like this: "streetID:1500001775:32:8111000:51:Konrad-Adenauer-Straße:Stuttgart:Konrad-Adenauer-Straße::Konrad-Adenauer-Straße:70173:ANY:DIVA_SINGLEHOUSE:3513826:755185:NBWT:VVS:0"
To find a value for an address, enter the origin and destination in the VVS timetable information (https://www3.vvs.de/), submit as search, decode the browser URL and format the deeplink parameter with a JSON formatter.