GTFS Realtime (GTFS-RT)

Kurzbeschreibung

GTFS Realtime (GTFS-RT) ist eine Erweiterung zu GTFS Static und reichert die statischen Transit-Informationen mit Echtzeitinformationen an. Die GTFS-Realtime-Daten sind auf die GTFS-Static-Daten abgestimmt. Der Realtime-Feed umfasst alle bekannten Änderungen im öV Schweiz im gesamten Vorschaufenster (drei Stunden) für alle Verkehrsunternehmen, die Echtzeitdaten liefern.

Fachliche Beschreibung

GTFS-RT erlaubt die Anreicherung der statischen Transit-Informationen mit drei verschiedenen Arten der Zusatzinformation. Diese drei Anreicherungen werden üblicherweise via HTTP einzeln zur Verfügung gestellt und regelmässig aktualisiert, somit können Entwickler auswählen, mit welchen Echtzeitdaten sie ihre Applikationen anreichern möchten.

Die drei Arten der Zusatzinformation sind:

• Trip Updates (welche hier hauptsächlich beschrieben werden)
• Service Alerts (GTFS-SA)
• Vehicle Positions (werden auf der Open-Data-Plattform Mobilität Schweiz nicht publiziert)

Das Schweizer GTFS Profil, welches im Detail die aus dem Standard übernommenen, bzw. vom Standard abweichenden Eigenschaften beschreibt, findet sich hier: https://www.oev-info.ch/datenmanagement/ski/standards-der-ski (der Link führt auf die Übersichtsseite, da das Dokument (General Transit Feed Specification (GTFS) PROFILE SWITZERLAND) derzeit noch häufig angepasst wird).

Bitte beachten: An Feiertagen (z. B. Ostermontag, Pfingstmontag u. a.) findet keine Aktualisierung statt.

Trip Updates

Beispiel: „Bus 18 hat aktuell 10 Minuten Verspätung.“

Hier werden Verspätungen, geänderte Routen, Ersatzfahrzeuge oder Ausfälle für einzelne Linien laufend publiziert, um den Fahrgästen eine möglichst exakte Planung zu ermöglichen.

Solange über VDV454 nicht immer eine SJYID geliefert wird, wird für die Fälle, in denen keine SJYID vorliegt, der VDV454-FahrtBezeichner in GTFS-RT in original_trip_id geliefert:

// Matches the original_trip_id in GTFS static.
optional string original_trip_id = 8;

Service Alerts

Beispiel: „Haltestelle Bern, Weissenbühl ist aufgrund eines Unfalls aktuell geschlossen.“

Im Falle von Verschiebung der Haltekante oder allgemein unvorhergesehenen Ereignissen, die eine Haltestelle, eine Route oder das gesamte Netzwerk beeinflussen, können kurze Meldungen publiziert werden, um die Fahrgäste auf dem Laufenden zu halten und zu erklären, was der Grund für die Änderung ist.

Datensatz GTFS-RT: Service Alerts (Ereignisinformationen)

Cookbook: GTFS-RT: Service Alerts (Ereignisinformationen Schweiz)

Vehicle Positions

Beispiel: „Dieser Bus befindet sich um 18h23 an der Haltestelle Bern, Bahnhof.“

Hier können Informationen zum Standort von einzelnen Transit-Fahrzeugen publiziert werden. Zusätzlich können auch die aktuelle Auslastung des Fahrzeugs, der Fahrzeugtyp oder ähnliche Informationen bereitgestellt werden.

Die Vehicle Positions stehen auf der Plattform nicht zur Verfügung.

Wichtige Konzepte

• GTFS Static (auch bekannt als GTFS Schedule): Publikation von statischen Transit-Informationen im GTFS-Format.
• GTFS Realtime: Publikation von Echtzeit-Transit-Informationen als Anreicherung der statischen GTFS-Daten, in der Form von Protocol Buffers.

Die einzelnen Elemente werden auf obengenannten Seiten des Standards im Detail erklärt, deshalb werden sie hier nicht alle wiedergegeben.

Technische Beschreibung

Die Trip Updates werden über einen GET Request zur Verfügung gestellt. Sie werden jeweils für 30 Sekunden gecacht, es gibt also nur 2x pro Minute neue Daten.
Um unser Caching zu optimieren, sendet der API-Manager ein Redirect mit einem neuen Link, deshalb müssen bei der Nutzung dieses Services immer Redirects aktiviert sein. Bei vielen Code-Bibliotheken kann dies mit entsprechenden Parametern wie z. B. “allow_redirects” realisiert werden.

Autorisierung und Open Services

Für den Zugriff auf diese API ist ein API-Key notwendig. Er kann über unseren API Manager bezogen werden, siehe dazu die Anleitung in Howto: Zugriff auf unsere APIs mit API-Keys.

Maximale Anzahl Abfragen pro Minute

Sie können mit ihrem Schlüssel maximal zwei Abfragen pro Minute auf die Schnittstelle durchführen. Es handelt sich um ein Sliding Window.

Bei zu raschem Anfragen kommt folgende Meldung zurück:

{
    "error": "Rate limit exceeded"
}

Bezug zu GFTS Static

Jeder GTFS-RT-Feed basiert auf einem GTFS Static. Dieses wird jeweils montags und donnerstags zur Verfügung gestellt (für den Störungsfall siehe nächster Abschnitt). Jeweils um 15 Uhr wird der GTFS-RT-Feed auf das neue GTFS Static umgestellt. Da Identifier (“service_id”, “trip_id”) mit jeder Version des GTFS Static ändern können, ist der Bezug auf das richtige GTFS Static zentral für eine korrekte Implementierung der Schnittstelle.

Im Header wird im Element feed_version (Schreibweise in .json: FeedVersion) auf die jeweils passende GTFS-Static-Version verwiesen. Bei der Ansicht als JSON könnte der Header dann folgendermassen aussehen (JSON nur zu Testzwecken nutzen, siehe unten):

  "Header": {
    "GtfsRealtimeVersion": "1.0",
    "Incrementality": "FullDataset",
    "Timestamp": 1727429583,
    "FeedVersion": "20240926"
  }

Im Störungsfall

Der GTFS-Static-Export wird schnellstmöglich veröffentlicht, gefolgt von GTFS Realtime ca. 5–6 Stunden später, spätestens jedoch bis 18:00 Uhr desselben Tages. Sollte dies nicht realisierbar sein, erfolgt die Aktivierung der neuen Daten in GTFS Realtime am Folgetag.

Beispiel: Die neuen GTFS-Static-Daten konnten erst am Nachmittag publiziert werden. Die Aktivierung der GTFS-Realtime-Daten folgt am nächsten Tag um ca. 08:00 Uhr

URL für den Aufruf

HTTP GET auf https://api.opentransportdata.swiss/la/gtfs-rt

(Achtung: Kein Schluss “/”)

Headers:

• Content-Type: “application/octet-stream”
• User-Agent muss gesetzt sein (beliebiger Wert)
• “Accept-Encoding: br, gzip, deflate”
• Redirections müssen erlaubt sein.

Beispiel in curl

curl -H "Authorization: Bearer eyJvcmciOiI2NDA2NTFhNTIyZmEwNTAwMDEyOWJiZTEiLCJpZCI6ImZjNzdjMzk2M2MwNjRjYzM4ZmNjOWZjYWQ4MjVlZWZkIiwiaCI6Im11cm11cjEyOCJ9"  -L -H "User-Agent: testuser" https://api.opentransportdata.swiss/la/gtfs-rt --compressed --output gtfs_rt_as_proto_buf.pb

Struktur der Daten (Protocol Buffer)

Das Datenformat GTFS Realtime basiert auf Protocol Buffers, welches ein sprach- und plattformneutraler Mechanismus ist, um Daten in eine serielle Reihenfolge zu bringen. Es ist als Binärformat konzipiert, was es kleiner, schneller und einfacher als XML macht. Die Datenstruktur ist in einem sog. gtfs-realtime.proto-File definiert, welches zum Generieren von Quellcode benutzt wird, um die strukturierten Daten einfach in verschiedene Sprachen (Java, C++, Python, etc.) zu übersetzen.

Struktur der Daten (JSON)

Alternativ stellt die Plattform auch eine JSON-Implementierung zur Verfügung.

Die Abfrage erfolgt dann über die URL:

HTTP GET https://api.opentransportdata.swiss/la/gtfs-rt?format=JSON

Die JSON-Variante ist jedoch nicht standardisiert.

Nutzung von JSON nur zu Testzwecken

JSON darf nur zu Testzwecken genutzt werden, wenn z.B. ein Entwickler einer neuen App in lesbarer Form sehen will, was für Daten in unserem GTFS-RT enthalten sind.

Am Ende sollte die GTFS-RT-Schnittstelle nicht in lesbarem JSON, sondern binär betrieben werden (ohne ?FORMAT=JSON) aus folgenden Gründen:

• binär ist viel performanter als JSON und in JSON sind viel mehr Daten zu übermitteln und einzulesen (eine JSON-Meldung wird bis zu ca. 11 MB gross),
• JSON ist nicht spezifiziert, bei binärem GTFS-RT kann sich der GTFS-Client hingegen darauf verlassen, dass es dem GTFS-RT-Standard entspricht

Genauigkeit

Die Verspätungen haben eine Genauigkeit von einer Zehntelminute (0.1 min = 6 s).

Interpretation der Daten

Für die genaue Interpretation der Daten kann direkt die GTFS-Spezifikation konsultiert werden.

Der grösste Spezialfall sind die Steige, welche auf der GTFS-Seite beschrieben sind.

Weitere wichtige Punkte

• GTFS-RT liefert nur neue Daten, wenn sich etwas geändert hat. Dabei wird von unserem System nur die Abfahrtsprognose beachtet. Sollte die Abfahrtsprognose bleiben und sich nur die Ankunftsprognose ändern, so wird für die betroffene Fahrt keine GTFS-RT-Meldung generiert.
• Wenn eine Fahrt pünktlich fährt, so wird sie mit innerhalb von StopTimeUpdate mit “Delay”: 0 ausgegeben.
• Beispiel

    {
      "id": ".ojp-92-206.1.TA.50.j26|20260624",
      "tripUpdate": {
        "trip": {
          "tripId": ".ojp-92-206.1.TA.50.j26",
          "startTime": "12:41:00",
          "startDate": "20260624",
          "scheduleRelationship": "SCHEDULED",
          "routeId": "92-206-j26-1",
          "originalTripId": "85:876:6037_103"
        },
        "stopTimeUpdate": [
          {
            "stopSequence": 1,
            "departure": {
              "delay": 0
            },
            "stopId": "ch:1:sloid:93924:0:2",
            "scheduleRelationship": "SCHEDULED"
          },
          {
            "stopSequence": 8,
            "arrival": {
              "delay": 30
            },
            "departure": {
              "delay": 30
            },
            "stopId": "ch:1:sloid:93932:0:1",
            "scheduleRelationship": "SCHEDULED"
          },
          {
            "stopSequence": 9,
            "arrival": {
              "delay": 0
            },
            "departure": {
              "delay": 0
            },
            "stopId": "ch:1:sloid:93933:0:1",
            "scheduleRelationship": "SCHEDULED"
          }
        ]
      }
    },

Fragen & Anworten