Zum Inhalt springen

TripRequest

Die TripRequest ist ein Open Service. TripRequest ist eine spezielle Form der Fahrtprognose und wird über VDV431 TripRequest abgebildet.

Es ist wichtig zu verstehen, dass diese Plattform nur ein Subset der Möglichkeiten von TripRequest umsetzt. Die untenstehende Dokumentation erläutert TripRequest und die Umsetzung durch die SBB.

Fachliche Beschreibung

TripRequest ist ein Routenplaner. Als Input werden ein Starthalt und ein Zielhalt erwartet. Abfahrts- und Ankunftszeit können auch angegeben werden.

Die Umsetzung der SBB erlaubt es nur, nach direkten Fahrten zu suchen. Z.B.:

  • Bern – Olten findet eine Antwort,_ da es direkte Fahrten gibt.
  • Lausanne – Chur findet keine,  da man immer mind. 1 mal umsteigen muss.

 

Wichtige Konzepte

  • Haltestellen: Hierfür können auch die Datensätze DiDok oder Haltestellen beigezogen werden.
  • Fahrten: 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.
  • Fahrplan: Ein Fahrplan legt im öffentlichen Personennah- und -fernverkehr und im Schienengüterverkehr den Fahrtverlauf eines Verkehrsmittels fest. Dabei notwendige Angaben sind Zugnummer, Verkehrstage, Fahrweg, Ankunfts-, Abfahrts- und Durchfahrtszeiten an den Haltestellen sowie die zulässigen Geschwindigkeiten in den einzelnen Abschnitten des Fahrwegs.
  • Prognose: Die Prognose sind die in der Zukunft liegenden Verkehrszeiten eines Zuges, die ausgehende vom aktuellen Standort des Zuges berechnet werden. Dabei werden Konflikte und deren aktuell intendierten Regelungen in den nächsten x Minuten berücksichtigt. Den weiteren Verlauf der Prognose wird nach einer weniger aufwendigen Methode berechnet
  • Verkehrsmittel (VM): Entweder gleichbedeutend mit Fahrzeugen (Zug, Schiff, Tram, Bus) der verschiedenen Verkehrsträger oder im Sinne von «Verkehrssystem» gebraucht (öffentliches Verkehrsmittel usw.).
  • DateTime in Response: Es handelt sich immer um Zulu-Zeit (d.h. UTC).  Es gilt im Sommer zwei Stunden und im Winter eine Stunde dazu zu zählen.

Technische Aspekte

API-Explorer

Authorisierung und Open Services

Für den Zugriff auf diese API ist ein API-Key notwendig. Es kann über das Developer Portal bezogen werden.
Das Token muss im HTTP Header als „Authorization“ mitgeschickt werden.

URL für den Aufruf

HTTP POST auf https://api.opentransportdata.swiss/trias

(Achtung: Kein Schluss „/“)

Mit dem  Authorization Header und Content-Type=  „text/XML“ oder „application/XML“

Authorization header

Beispiel einer Abfrage

Für  den vorliegenden TripRequest-Dienst kann der Entwickler Start- und Zielhaltestelle (DiDok-ID) und optional für einen zukünftigen Zeitpunkt (Default = jetzt) die entsprechenden Echtzeitdaten abfragen. Er erhält eine Echtzeitinformation, sofern vorhanden.

Dieser Request wird als Body übermittelt.

 Erläuterungen der Elemente des Requests

Der Request hat die folgenden zentralen Elemente:

Name Obligat? Beschreibung Beispiel
Origin  Ja Ortsdaten für den Abfahrtsort
 
LocationRef  Ja
StopPointRef  Ja  Die Haltestelle als Didok-Code. 8500320
DepArrTime  Nein  Abfahrts- oder Ankunftszeit. Ohne Zeitangabe wird die aktuelle Uhrzeit verwendet. 2016-08-01T09:11:40
Via  Nein, Mehrere Ein oder mehrere Via-Orte. Die angegebenen Via-Orte müssen in der vorgegebenen Reihenfolge erreicht werden. Der Server darf eine Via-Haltestelle durch eine äquivalente Haltestelle ersetzen

Achtung: Nicht zu verwenden

NoChangeAt  Nein, Mehrere  Gibt Haltestellen an, an denen nicht umgestiegen werden darf.

Achtung: Wird nicht verwendet.

Destination  Ja Ortsdaten für den Zielort

Hat denselben Aufbau wie Origin

Params  Nein

Aufbau von Params:

Name Obligat? Beschreibung Beispiel
IncludeTrackSections  Nein Die TrackSections werden angezeigt. Default = true.

Umgesetzt, aber immer nur ein Track, also nicht speziell interessant.

true
IncludeLegProjection  Nein Dieser Parameter ist nicht umgesetzt. true
IncludeIntermediateStops  Nein Umgesetzt, aber keine intermediate Stops angezeigt. true
NumberOfResults Nein Anzahl der Verbindungsauskünfte, die der Benutzer mindestens erwartet. Default = 3 und es werden immer wenigstens 3 ausgegeben, auch wenn der Wert tiefer ist. 20

Die folgenden Parameter gemäss VDV431 sind ebenfalls nicht umgesetzt:

  • PtModeFilter: Filter nach Verkehrsmitteltypen
  • LineFilter: Erlaubte Linien (ggf. verfeinert auf Richtungen)
  • OperatorFilter: Filter nach Verkehrsunternehmen
  • NoSingleStep: Legt fest, ob der Benutzer eine Stufe bewältigen kann. Falls nein, wird dieser Parameter auf true gesetzt.
  • NoStairs: Legt fest, ob der Benutzer eine Treppe bewältigen kann. Falls nein, wird dieser Parameter gesetzt.
  • NoEscalator: Legt fest, ob der Benutzer eine Rolltreppe benutzen kann. Falls nein, wird dieser Parameter gesetzt.
  • NoElevator: legt fest, ob der Benutzer einen Aufzug benutzen kann.  Falls nein, wird dieser Parameter gesetzt.
  • NoRamp: Legt fest, ob der Benutzer eine Rampe bewältigen kann. Falls nein, wird dieser Parameter gesetzt.
  • LevelEntrace: Legt fest, ob der Benutzer beim Ein- und Aussteigen in und aus Fahrzeugen einen ebenen Zugang benötigt. Dazu reicht u.U. auch ein Hublift am Fahrzeug oder am Bahnsteig. Falls der ebene Zugang notwendig ist, wird dieser Parameter gesetzt.
  • BikeTransport: Legt fest, ob der Benutzer ein Fahrrad an Bord der Verkehrsmittel mitnehmen will. Falls ja, wird dieser Parameter gesetzt.
  • WalkSpeed: Veränderung der Standardgehgeschwindigkeit in Prozent. Der Wert 100 stellt den Standard dar. Werte kleiner 100 stellen eine langsamere Geschwindigkeit dar, Werte grösser 100 eine schnellere.
  • IgnoreRealtime Data: Wenn dieser Parameter gesetzt ist, sollen in der Verbindungssuche keine Echtzeitdaten oder Störungsinformationen sondern nur Sollfahrplandaten berücksichtigt werden.
  • ImmediateTripStart: Wenn dieser Parameter gesetzt ist, soll die zu suchende Verbindung unmittelbar an der angegeben Startsituation beginnen. Eine Optimierung der Abfahrtszeit am Start nach der Regel „Starte so spät wie möglich, solange nur die gleiche Ankunftszeit am ziel gewährleistet ist“, ist dann nicht notwendig.
  • InterchangeLimit: Anzahl der maximal zugelassenen Umsteigevorgänge. Achtung: Dieser Parameter wird ignoriert.
  • AlgorithmType: Art der Zielfunktion, nach der der Algorithmus die Verbindung optimieren soll:  fastest, minChanges, leastWalking, leastCost
  • ItModesToCover: Für jeden IV-Typ in dieser Liste soll eine eigene monomodale Verbindung gefunden werden – zusätzlich zu den intermodalen Verbindungen.
  • IncludeTurnDescription: Legt fest, ob im Resultat Routenhinweise mit Abbiegeempfehlungen mit ausgegeben werden sollen. Default ist false. Parameter wird ignoriert.
  • IncludeAccessibilitiy: Legt fest, ob im Resultat Informationen zur Barrierefreiheit mit ausgegeben werden sollen. Default ist false. Parameter wird ignoriert.
  • IncludeFares: Legt fest, ob im Resultat Tarifinformationen mit ausgegeben werden sollen. Default ist false. Parameter wird ignoriert.
  • IncludeOperatingDays: Legt fest, ob im Resultat Informationen zu den Verkehrstagen mit ausgegeben werden sollen. Default ist false.
  • FaresParam: Parameter für die Tarifermittlung. Parameter werden ignoriert.
  • Extension: Erweiterungen. Keine umgesetzt.

Ausschnitt und Erläuterung einer Response

Die Antwort hat folgenden grundsätzlichen Aufbau:

Die Antwort hat dabei die folgenden Elemente

  • TripResponse: Die Antwort selber
  • Sie enthält einzelne TripResults.

MoreData ist immer false, da alle Daten geliefert werden.

Response: Trip

Name Obligat? Beschreibung Beispiel
ResultID Ja ID für interne Zwecke  ID-95725E00-4D45-4651-99A7-3BB4AFFA4E0D
TripID Ja ID für interne Zwecke  ID-95725E00-4D45-4651-99A7-3BB4AFFA4E0D
Duration Ja Gesamtdauer in Minuten 7
StartTime  Ja  Startzeit des Trips in Zuluzeit 2016-08-01T07:19:00Z
EndTime  Ja  Endzeit des Trips in Zuluzeit 2016-08-01T07:26:00Z
Interchanges  Ja  Anzahl Umsteigen 0

Response TripLeg

Name Obligat? Beschreibung Beispiel
 LegID Ja Laufnummer des Legs

In der Umsetzung der SBB immer 1.

1
TimedLeg Ja VDV431 verwendet verschiedene Typen von Legs. In der aktuellen Umsetzung handelt es sich immer um TimedLegs.
LegBoard Ja Der Startort des Legs
StopPointRef Ja Didok-Code 8500320
StopPointName Ja Bezeichnung des Didok-Codes. Achtung: Sprache ist immer DE.  –
ServiceDeparture Ja Abfahrtszeitstruktur
TimetabledTime Ja Abfahrtszeit gemäss Fahrplan 20160801T07:19:00Z
EstimatedTime Nein Abfahrtszeit gemäss Prognose. Bei Teilen der Fahrt in der Vergangenheit handelt es sich um die letzte Prognose oder um Ist-Daten. 20160801T07:19:00Z
EstimatedBay Nein Name des Steigs/Haltestelle, wo in das Fahrzeug ein- oder ausgestiegen werden muss (bei Verwen-dung in Zusammenhang mit einer konkreten Verbindungsauskunft, wenn in StopPointName ein allgemeiner Name angegeben ist, ähnlich Haltestellen-name). Nach Planungsstand.

Planned Bay Nein Name des Steigs/Haltestelle, wo in das Fahrzeug ein- oder ausgestiegen werden muss (bei Verwen-dung in Zusammenhang mit einer konkreten Verbindungsauskunft, wenn in StopPointName ein allgemeiner Name angegeben ist, ähnlich Haltestellen-name). Nach letztem Prognosestand.

StopSequenceNumber Ja Sequenznummer des Stops 1
LegIntermediate Nein Gleiche Struktur wie LegBoard für Zwischenhalt. Enthält sowohl ServiceDeparture wie auch ServiceArrival als Zeiten.
LegAlight Ja Gleiche Struktur wie LegBoard für den Endhalt. Enthält nur Servicearrival als Zeit.
Service Ja Die Angaben zum Service für dieses Leg
LegTrack Nein Detaillierter (geometrischer) Verlauf.

Service

Die Struktur „Service“ ist hier beschrieben.

Fehler / Probleme

Die Antwort enthält eine „ErrorMessage“, wenn es Probleme mit der Ausführung des Requests gab:

screenshot-3

Anmerkungen

Die folgenden Angaben sind für externe Entwickler wichtig:

  • EstimatedBay und PlannedBay beinhalten die Gleisinformationen, wie sie durch die Systeme angeliefert werden. D.h. Gleis „12“ und Gleis „12A“ werden als zwei unterschiedliche Gleise betrachtet. In Zürich HB gibt es al geplant z.B. „41/42“. Im PlannedBay kann es dann nur noch „41“ sein.
  • Aufgrund von Restriktionen können nur direkte Züge angezeigt werden.
  • Metahaltestellen werden auch nicht berücksichtigt. D.h.  Es wird ein Resultat von Wankdorf nach Bern gefunden. Von Wankdorf, Bahnhof nach Bern nicht.
  • Ausgefallene Fahrten werden (anders als im StopEvent) nicht angezeigt oder markiert.

Weiterführende Angaben


Wichtige Antworten

  1. Wenn ich TripRequests auf Bus & Tram-Haltestellen mache sieht das Destination-Tag praktisch immer (hab noch kein Gegenbeispiel gefunden) insofern komisch aus, als dass DestinationStopPointRef leer ist und beim DestinationText.Text komische Sonderzeichen hinter dem Haltestellen namen kommen.

    Bsp. Request:

     <?xml version="1.0" encoding="UTF-8"?>
    <ns2:Trias xmlns:ns2="http://www.vdv.de/trias" xmlns="http://www.siri.org.uk/siri" xmlns:ns3="http://www.ifopt.org.uk/acsb" xmlns:ns4="http://www.ifopt.org.uk/ifopt" xmlns:ns5="http://datex2.eu/schema/1_0/1_0" version="1.1">
       <ns2:ServiceRequest>
          <RequestTimestamp>2017-05-27T14:38:19.891+02:00</RequestTimestamp>
          <RequestorRef>fiasim.ch</RequestorRef>
          <ns2:RequestPayload>
             <ns2:TripRequest>
                <ns2:Origin>
                   <ns2:LocationRef>
                      <ns2:StopPointRef>8589002</ns2:StopPointRef>
                   </ns2:LocationRef>
                   <ns2:DepArrTime>2017-05-27T14:38:19.890+02:00</ns2:DepArrTime>
                </ns2:Origin>
                <ns2:Destination>
                   <ns2:LocationRef>
                      <ns2:StopPointRef>8507050</ns2:StopPointRef>
                   </ns2:LocationRef>
                </ns2:Destination>
                <ns2:Params>
                   <ns2:NumberOfResults>10</ns2:NumberOfResults>
                   <ns2:InterchangeLimit>0</ns2:InterchangeLimit>
                </ns2:Params>
             </ns2:TripRequest>
          </ns2:RequestPayload>
       </ns2:ServiceRequest>
    </ns2:Trias>

    Das Service-Tag sieht dann z.B. so aus:

                              <Service>
                               <OperatingDayRef>2017-05-27</OperatingDayRef>
                               <JourneyRef>odp:06008::R:j17:12541:12541</JourneyRef>
                               <LineRef>odp:06008::R</LineRef>
                               <DirectionRef>return</DirectionRef>
                               <Mode>
                                  <PtMode>tram</PtMode>
                                  <TramSubmode>undefined</TramSubmode>
                                  <Name>
                                     <Text>Tram</Text>
                                     <Language>DE</Language>
                                  </Name>
                               </Mode>
                               <PublishedLineName>
                                  <Text>8</Text>
                                  <Language>DE</Language>
                               </PublishedLineName>
                               <OperatorRef>odp:827</OperatorRef>
                               <OriginText>
                                  <Text />
                                  <Language>DE</Language>
                               </OriginText>
                               <DestinationStopPointRef />
                               <DestinationText>
                                  <Text>Bern Brünnen Westside, Bahnhof                    &amp;#xD;</Text>
                                  <Language>DE</Language>
                               </DestinationText>
                            </Service>

    Wenn die Abfrage aber auf Zugshalte gemacht wird, stimmt es offenbar meist:

                            <Service>
                               <OperatingDayRef>2017-05-27</OperatingDayRef>
                               <JourneyRef>odp:80050:Y:H:j17:4175:4175</JourneyRef>
                               <LineRef>odp:80050:Y:H</LineRef>
                               <DirectionRef>outward</DirectionRef>
                               <Mode>
                                  <PtMode>rail</PtMode>
                                  <RailSubmode>undefined</RailSubmode>
                                  <Name>
                                     <Text>RegioExpress</Text>
                                     <Language>DE</Language>
                                  </Name>
                               </Mode>
                               <PublishedLineName>
                                  <Text />
                                  <Language>DE</Language>
                               </PublishedLineName>
                               <OperatorRef>odp:33</OperatorRef>
                               <Attribute>
                                  <Text>
                                     <Text>LÖTSCHBERGER</Text>
                                     <Language>DE</Language>
                                  </Text>
                                  <Code />
                                  <Mandatory>false</Mandatory>
                               </Attribute>
                               <Attribute>
                                  <Text>
                                     <Text>Billettkauf im Zug möglich (mit Zuschlag)</Text>
                                     <Language>DE</Language>
                                  </Text>
                                  <Code />
                                  <Mandatory>false</Mandatory>
                               </Attribute>
                               <Attribute>
                                  <Text>
                                     <Text>1 Zug-2 Ziele: bitte Anschriften beachten</Text>
                                     <Language>DE</Language>
                                  </Text>
                                  <Code />
                                  <Mandatory>false</Mandatory>
                               </Attribute>
                               <Attribute>
                                  <Text>
                                     <Text>Reservierung möglich</Text>
                                     <Language>DE</Language>
                                  </Text>
                                  <Code />
                                  <Mandatory>false</Mandatory>
                               </Attribute>
                               <OriginText>
                                  <Text />
                                  <Language>DE</Language>
                               </OriginText>
                               <DestinationStopPointRef>8507483</DestinationStopPointRef>
                               <DestinationText>
                                  <Text>Spiez</Text>
                                  <Language>DE</Language>
                               </DestinationText>
                            </Service>
  2. Gibt es ein Update dazu? Das Problem besteht leider noch immer...

  3. Hallo! Ja, das gibt es:
    Das Feld DestinationStopPointRef ist ein optionales Feld in Trias. In der neusten Version (nächster Release, Datum noch nicht bekannt) wurde die Ausgabe so geändert, dass das optionale Feld DestinationStopPointRef bei der Ausgabe weggelassen wird, wenn es nicht befüllt werden kann.

Diskussion fortsetzen auf disc.opentransportdata.swiss