Skip to content
LoginRegister
DEENFRIT
Home
Open Data-Plattform Mobilität Schweiz
  2. Cookbook
  3. Open Journey Planner (OJP)

Open Journey Planner (OJP)

Stand Januar 2024.  Informationen zu kontinuierlichen Anpassungen findest Du in unserem Changelog.

Hintergrund

Was ist OJP?

Die Abkürzung hat drei Bedeutungen:

  1. Der Schnittstellen-Standard CEN/TS 17118 «Open API for Distributed Journey Planning», der in der Delegierten Verordnung (EU 2017/1926) für die Mitgliedsstaaten der Europäischen Union als verbindlich erklärt wurde.
  2. Das Routing-Backend-System «Open Journey Planner» zur Berechnung von Routen mit dem öffentlichen Verkehr (öV), Fusswegen und weiteren Mobilitätsangeboten.
  3. Die OJP-Schnittstelle, also die dem OJP-Standard entsprechende Schnittstelle des OJP-Systems. Sie ist im Kern ein XML–Standard mit einem Request/Response-Verhalten. Für die Schweiz wird wie bei allen CEN-Standards ein Profil entwickelt (was wird unterstützt und was nicht). Das Profil ist hier verlinkt.

Auf dieser Open Data-Plattform wird, wenn nicht abweichend angegeben, die Abkürzung «OJP» meist für das System “Open Journey Planner” genutzt.

Auf dieser Seite schreiben wir zur Unterscheidung vom OJP-Standard (CEN-Norm), dem OJP-System (Routing-System), und der OJP-Schnittstelle.

Wer steckt dahinter?

Wie oben beschrieben wird der OJP-Standard von der Comité Européen de Normalisation (CEN) vorangetrieben. Die Geschäftsstelle Systemaufgaben Kundeninformation Plus (SKI+) wirkt im Auftrag des Bundesamt für Verkehr (BAV) an der Weiterentwicklung des OJP-Standards aktiv mit. Der OJP-Standard basiert auf CENs Network Timetable Exchange (NeTEx) Standard. Die Datenmodelle beider Standards implementieren wiederum das Referenzdatenmodell für den öffentlichen Verkehr in Europa, genannt Transmodel.

Das OJP-System wird von einem externen Dienstleister der SKI+ entwickelt. Das System basiert auf einem proprietären Produkt des externen Dienstleisters. Das OJP-System kann mit dem OJP-Standard angesteuert werden.

Die OJP-Schnittstelle basiert auf dem Travellors Realtime Information Advisory Standard (TRIAS), welcher der Weisung 431 des Verband Deutscher Verkehrsunternehmen (VDV) folgt.

Eine Demo zum Ausprobieren des OJP-Systems unter Einsatz des OJP-Standards findet sich hier: OJP Demo

Mehr Informationen zur Beurteilung von OJP als Standard findest Du im Bericht des BAV.

Warum bietet die Open Data-Plattform das an?

Der OJP-Standard erlaubt eine offene und standardisierte Schnittstelle für die “verteilte Routenplanung”. Somit können verschiedene Systeme nach diesem auf europäischer Ebene entwickelten Standard zusammenarbeiten, um eine grenzüberschreitende oder verschiedene Transportmodalitäten integrierende Reiseplanung anzubieten, oder um neue innovative Informationsdienste zu ermöglichen.

Das OJP-System dient der Erfüllung des Auftrags des BAV nach einem diskriminierungsfreien und intermodalen Router, welcher über einer dem OJP-Standard entsprechenden Schnittstelle angesteuert werden kann. Das OJP-System ist dafür gedacht, dass dessen Dienste für die Entwicklung von Endkunden-Applikationen genutzt werden. Der direkte Kontakt mit Kundinnen und Kunden sowie deren Daten verbleiben bei diesen Endkunden-Applikationen!

Wichtig ist zu verstehen, dass trotz ihrer ähnlichen Benennung der Router und der Standard zwei im Grunde unabhängige Dinge sind.

Wie komme ich an die Daten/Schnittstellen ran?

Daten

Wie beschrieben ist OJP ein Standard/System/Schnittstelle, dementsprechend gibt es keinen Datei-Download

Wir empfehlen jedoch die GitHub-Seite Link oder unseren API-Schnittstelle, um ein Paar praktische Beispiel zu sehen.

Schnittstellen

Details zur OJP-API: https://opentransportdata.swiss/de/dataset/ojp2020 (produktiv seit 2020).

Details zu OJP API (2.0): https://opentransportdata.swiss/de/dataset/ojp2-0 (produktiv, noch in Entwicklung

Details zur OJP-Fare API: https://opentransportdata.swiss/de/dataset/ojpfare

Fachliche Beschreibung

Achtung: Die folgende Beschreibung fokussiert sich auf OJP2020 (also OJP-API v1.0). Für die Arbeit mit OJP-API 2.0 siehe https://opentransportdata.swiss/de/cookbook/ojp2entwicklung/.

Welche Services (Schnittstellen-Endpunkte) bietet der OJP-Standard?

Der OJP-Standard definiert verschiedene Schnittstellen-Endpunkte (im Folgenden nur als “Services” bezeichnet) an. In der Version 1.0 sind das 7 “Kern-Services” und in der Version 2.0 sind es 9 “Kern-Services”. Diese Services werden durch das OJP-System bedient.

Das OJP-System unterstützt alle 7 der Version 1.0 der Services die abgerufen und verknüpft werden (LinkedServices, beschreiben wir im technischen Abschnitt weiter unten) können. Sortiert nach ihrer Wichtigkeit:

  1. Deine Situation: Du möchtest mit deiner Familie eine Route mit verschiedenen Transportmitteln berechnen?
    • Dann brauchst Du den TripRequest
    • Was der Service tut: Bei diesem Service führt das bedienende System (bei uns das OJP-System) ein Routing durch.
    • Was es der Service braucht: Bei der Eingabe eines Start- und eines Zielpunktes (jeweils Koordinate, Adresse, POI oder Haltestelle) berechnet das OJP-System Verbindungen vom Start- zum Zielpunkt. Verschiedene Modi können mit ModesToCover zusätzlich angefragt werden. Derzeit stehen folgende Modi zur Verfügung: öffentlicher Verkehr; Fussweg; Fahrrad; selbst gefahrenes Auto; Sharing-Angebote (Fahrrad, e-Scooter, Carsharing).
    • Was der zurück Service gibt: Das Routing beinhaltet sowohl ein öV-Routing (unter Berücksichtigung der aktuellen Fahrzeiten und Störungen), als auch ein kartenbasiertes Individual Verkehr-Routing (bspw. mit dem eigenen Auto) auf Basis von OpenStreetMap (OSM). Auf Wunsch können Sie mit dem Ausgabeparameter Link-Projection die effektiven geografischen Wege anfragen, und für Fusswege ist meist auch eine TurnDescription verfügbar (verbal beschriebene Navigation).
    • Mehr Details zu diesem Service unter folgendem Link: OJPTripRequest
  2. Deine Situation: Du möchtest deinen Gästen die Haltestellen und Points-of-Interest in deiner Nähe anzeigen?
    • Dann brauchst Du den LocationInformationRequest
    • Was der Service tut: Dieser Service ermittelt die nächstgelegenen Orte.
    • Was der Service braucht: Bei der Eingabe einer Koordinate oder einer Adresse bestimmt das OJP-System mit einer Umkreissuche die passenden Orte.
    • Was der Service gibt: Die Haltestellen und Points-of-Interest in der Nähe des angegebenen Orts.
    • Mehr Details zu diesem Service unter folgendem Link: OJPLocationInformationRequest
  3. Deine Situation: Du willst einen Abfahrtsmonitor für die Haltestelle vor deinem Laden?
    • Dann brauchst Du den StopEventRequest
    • Was der Service tut: Der Service bestimmt die Abfahrts- und Ankunftszeiten einer Haltestelle.
    • Was der Service braucht: Bei der Eingabe muss eine spezifische Haltestelle angegeben werden.
    • Was der Service gibt: Die nächsten Abfahrten / Ankünfte einer bestimmten Haltestelle.
    • Mehr Details zu diesem Service unter folgendem Link: OJPStopEventRequest
  4. Deine Situation: Du brauchst alle Haltepunkte entlang der zuvor berechneten Reise?
    • Dann brauchst Du den TripInfoRequest
    • Was der Service tut: Dieser Service ermittelt weitere Details zu einer bereits berechneten “Journey” (Fahrt) abzufragen (s. TripRequest).
    • Was der Service braucht: Die zuvor ermittelte Journey muss mitgegeben werden.
    • Was der Service gibt: Details zu einer bereits berechneten “Journey” (Fahrt).
    • Mehr Details zu diesem Service unter folgendem Link: OJPTripInfoRequest
  5. Deine Situation: Du möchtest wissen wieviel die von dir angefragt Fahrt voraussichtlich kostet?
    • Dann brauchst Du den FareRequest
    • Was der Service tut: Bestimmt mithilfe der öV Kostenberechnungsinfrastruktur der Schweiz die voraussichtlichen Kosten einer übergebenen Fahrt.
    • Was der Service braucht: Die zuvor ermittelte “Journey” (Fahrt) muss mitgegeben werden.
    • Was der Service gibt: Der Preisberechnung von Trips, inklusive Discountfahrten und Berücksichtigung von Halbtax (“HTA”). Es sind nur Preisabfragen in der Schweiz möglich. WICHTIG: Die Preisauskunft ist nicht verbindlich. Der effektive Preis wird erst bei der Bestellung definiert. Die Anzahl Anfragen ist ebenfalls limitiert.
    • Mehr Details zu diesem Service unter folgendem Link: Beta: OJP Fares
  6. Deine Situation: Du möchtest eine Reise nach Österreich planen und geeignete Umstiegspunkte finden?
    • Dann brauchst Du den ExchangePointRequest
    • Was der Service tut: Liefert eine Liste von Halten die als Übergangspunkte zwischen zwei Regionen genutzt werden können. Die Abfrage ist Teil der verteilten Routen-Berechnung des OJP-Standards. Regionen sind solche die von anderen, verteilten Systemen bedient werden.
    • Was der Service braucht: Ein spezifischer Ort für den Übergangshalten zu benachbarten Systemen gesucht werden sollen, sowie entsprechende Parameter, bspw. über den Art der Ortes (POI, Halte, usw.).
    • Was der Service gibt: Entweder die Übergangshalten für den angefragten Ort, oder alle Übergangshalten, die für die Routenberechnung genutzt werden kann.
    • Bisher keine weiteren Details zu diesem Service.
  7. Deine Situation: Du möchtest eine Route berechnen von Bern zu Deiner Tante in Zürich reisen und vorher noch einen Zwischenhalt in Olten einlegen?
    • Dann brauchst Du den MultiPointTripRequest
    • Was der Service tut: Bei diesem Service führt das bedienende System (bei uns das OJP-System) ein Routing durch, genauso wie der TripRequest.
    • Was der Service braucht: Zusätzlich zum Start- und eines Zielpunkt (jeweils Koordinate, Adresse, POI oder Haltestelle) (wie beim TripRequest) braucht man Zwischenpunkten die explizit ein- oder ausgeschlossen werden müssen.
    • Was der Service gibt: Das gleiche wie im TripRequest und Das Routing beinhaltet sowohl ein öV-Routing (unter Berücksichtigung der aktuellen Fahrzeiten und Störungen), als auch ein kartenbasiertes Individual Verkehr-Routing (bspw. mit dem eigenen Auto) auf Basis von OpenStreetMap (OSM). Auf Wunsch können Sie mit dem Ausgabeparameter Link-Projection die effektiven geografischen Wege anfragen, und für Fusswege ist meist auch eine TurnDescription verfügbar (verbal beschriebene Navigation).
    • Bisher keine weiteren Details zu diesem Service.
  8. Deine Situation: Du hast vor einigen Tagen eine Route berechnen lassen. Nun ist der Reisetag gekommen und du möchtest aktuelle Informationen abrufen?
    • Dann brauchst Du den (ab Version 2.0) TripRefinementRequest
    • Was der Service tut: Einen bereits berechneten Trip zu aktualisieren. Wichtig ist hierbei, dass die Anfrage keine Neuberechnung ist!
    • Was der Service braucht: Einen bestehenden Trip mit Kontext und Parametern. Dabei können die Parameter im Sinne eines Filters wirken, bspw. dass nur die Teilergebnisse geliefert werden die keine Stufen enthalten.
    • Was der Service gibt: Der Service aktualisiert den Trip mit den gewünschten Ergänzungen, falls vorhanden. Wichtig:
      • Es kann sein dass der Service mehrere Trips liefert und nicht (nur) den angefragten.
      • Es kann passieren, dass der vorherige Trip bei dieser Anfrage “kaputt geht”. Dann muss der Trip neu berechnet werden.
      • Die Antwort des TripRefinementRequest ist also immer zu überprüfen!
    • Bisher keine weiteren Details zu diesem Service.
  9. Deine Situation: Du musst deinen geplanten Zwischenhalt in Olten verlängern? 
    • Dann brauchst Du den (ab Version 2.0) TripChangeRequest
    • Was der Service tut: Erlaubt es die Verweildauer an einem Zwischenhalt entlang eines Trips zu verlängern und entweder den Abschnitt davor oder danach zu erhalten. Die jeweils anderen Teile könnten somit neu berechnet werden.
    • Was der Service braucht: Einen bestehenden Leg sowie die gewünschten Anpassungen an diesem.
    • Was der Service gibt: Einen den wünschen entsprechend veränderten Trip.
    • Bisher keine weiteren Details zu diesem Service.
  10. SysRequest:
    1. Zusätzlich zu den 7 bzw. 9 Grundservices gibt es die Möglichkeit den Zustand des OJP (Version/DateFormat/usw.) abzufragen.
    2. Mehr Details zu diesem Service unter folgendem Link: OJP Sysrequest

Was sind die wichtigsten Begriffe und Konzepte die man kennen sollte?

Um die OJP-Schnittstelle einsetzen zu können muss man die folgenden Begriffe und Konzepte verinnerlichen.

  • StopPoint
    • Beschreibung: Ein StopPoint ist ein Halt entlang eines Fahrplans. Es kann sich um eine Haltestelle, ein Gleis, ein Sektor, eine Haltekante oder auch um ein dynamisches Element handeln. Der StopPoint wird über ein StopAssignment dem StopPlace zugewiesen.
  • StopPlace
    • Beschreibung: Der StopPlace ist die physische Repräsentation einer Haltestelle. Ein StopPlace kann in seiner Grösse variieren. Sehr grosse Haltestellen wie der Bahnhof Bern oder der Bahnhof Zürich bestehen aus mehreren StopPlaces.
  • Journey, die “Fahrt”
    • Beschreibung: Eine Fahrt ist die Beförderung von Kunden auf einem bestimmten Weg, einer bestimmten Fahrplan-Verbindung, mit einem bestimmten Verkehrsmittel-Fahrt, zu einer bestimmten Zeit, in eine bestimmte Richtung. Es gibt verschiedene Journey-Typen, z.B.: DatedJourney für eine Fahrt eines Verkehrsmittels an einem bestimmten Tag.
  • Trip, die “Reise”
    • Beschreibung: Eine “Reise” und somit eine unspezifische Form der konkreteren Fahrt. Ein Trip besteht aus Legs (s.u.).
  • Leg, der “Reiseabschnitt”
    • Beschreibung: Ein Abschnitt eines Trips. Es gibt die folgenden Legtypen:
      • ContinuousLeg: Ein Leg, das nicht an einen Fahrplan gebunden ist.
      • TimedLeg: Leg gemäss einem Fahrplan.
      • TransferLeg: Ein Leg, für einen Ort, an dem ein Umsteigen erfolgt.
  • Direction
    • Beschreibung: Alle Linien und Fahrten haben eine Richtung. Diese hilft primär den Transportunternehmen in ihrer Planung und allenfalls zur Anzeige einer “End/Zielstation”. Dies ist demnach ein “künstliches Attribut” und die Bedeutung der Richtung lässt sich nicht ableiten.
  • Facility
    • Beschreibung: Eine Facility ist ein Element, das an einem “Ort” (z.B. Haltestelle) oder auf einem “Service” (z.B. Fahrzeug) verfügbar ist. Ein Beispiel ist die Toilette am Bahnhof oder der Speisewagen. Aktuell werden sie aus den Angeboten in HRDF übernommen (siehe Verkehrshinweise). Das Mapping erfolgt gemäss Notes2FacilitiesMappingFile.
  • Mode
    • Beschreibung: Modes sind mögliche Verkehrsmittel. Zulässige Modes sind:
      • ContinuousMode: Mode, der nicht von einem Fahrplan abhängt.
      • IndividualModes: Individualverkehr.
      • PtMode: PtMode ist ein Mode im Public Transport.
      • TransferModes: Mode im Zusammenhang mit Umsteigen
      • XXXRef: Bei diesen Elementen handelt es sich um Referenzen. Im Endeffekt werden es generische schweizweite ID sein. Diese sind jedoch noch im Aufbau. Es wird hier als eine Evolution geben.

Technische Beschreibung

Zugriff auf das API

Um die API/Schnittstelle nutzen zu können braucht es einen Token. Dieser Token kann über das Developer Portal bezogen werden.

Alle Services für Version 1.0 sind über POST mit der URL https://api.opentransportdata.swiss/ojp2020 verfügbar.

Alle Services für Version 2.0 sind über POST mit der URL https://api.opentransportdata.swiss/ojp20  verfügbar.

Sie können die Schnittstelle hier ausprobieren https://opentransportdata.swiss/de/cookbook/open-journey-planner-ojp-api-explorer/

oder  https://opentdatach.github.io/api-explorer2/

Grundfunktionsweise API

Einfache Requests

Die OJP-Schnittstelle entspricht mehr einer klassischen SOAP XML-Schnittstelle als einer REST-Schnittstelle. Alle Zugriffe erfolgen über den genannten Endpunkt.

Zwei Header müssen gesetzt sein:

Der aktuelle Arbeitsschlüssel ist:

Die Unterscheidung der oben beschriebenen Dienste erfolgt über die entsprechenden Requests im Element ServiceRequest. Hier im Beispiel führen wir einen LocationInformationRequest aus.

Beachten Sie, dass sie als RequestorRef eine eindeutige Angabe machen. Es geht hierbei darum zu identifizieren von wem die Anfrage gestellt wird. Die Angabe sollte den Suffix “_test”, “_int” oder “_prod” beinhalten, damit wir bei späteren Analysen und Supportanfragen wissen, von welcher Umgebung zugegriffen worden ist.

Mehrere Requests in einer Meldung

Innerhalb eines ServiceRequest ist es möglich, beliebig viele verschiedene OJPXXXRequests einzufügen. Sie müssen auch nicht notgedrungen vom selben Typ sein.

Achtung: Die Antworten ist nicht in der Reihenfolge der gestellten Requests sortiert, sondern gemäss der Sequenz im Standards-XSD. Daher ist es bei solchen Anfragen enorm wichtig, dass die MessageIdentifier pro Request gesetzt sind und dann aus der Antwort ausgelesen werden können. Die Standard-Reihenfolge ist (Version 1.0):

  • ExchangePointsRequest
  • FareRequest
  • LocationInformationRequest
  • MultiPointRequest
  • StopEventRequest
  • TripInfoRequest
  • TripRequest

Einschränkungen und weiterführende Angaben

Einschränkungen

  • Verschiedene Modi sind noch nicht verfügbar.
  • Echtzeitinformation sind nur dort verfügbar, wo wir diese Information erhalten haben und über CUS beziehen können.

Weiterführende Angaben