TripRequest (TRIAS 2020)

(TRIAS TripRequest)

TripRequest est un open service (API). Il s’agit d’un type de prévision relative au trajet (un deuxième type étant TripInfoRequest). Il correspond au service « TripRequest » de VDV431.

Description technique
- Concepts importants
Détails techniques
Pour en savoir plus

Description technique

TripRequest offre une fonctionnalité de planificateur d’itinéraire. Données d’entrée nécessaires sont les arrêts de départ et d’arrivée. En plus, il est possible d’en ajouter l’heure de départ ou d’arrivée.

L’implémentation des CFF ne trouve que des trajets directs (sans changement de train ou de moyen de transport) :

Berne – Olten fournit un résultat, ils existent des trajets directs.
Lausanne – Chur ne fournit pas de résultat, il faut toujours changer de train.

Concepts importants

Halte : Les jeux de données suivants seront d’utilité : DiDok et la liste des gares
Trajet / voyage : Un trajet comprend le transport suivant un certain itinéraire et une certaine liaison selon l’horaire, à une certaine heure, utilisant un certain moyen de transport, dans une certaine direction.
Horaire : L’horaire, dans le contexte des transports publics (ainsi que du transport des marchandises sur rail), détermine l’itinéraire d’un moyen de transport. Il définit en plus les numéros des trains, les jours de service, la route, les heures d’arrivée, de départ et de passage pour toutes les haltes, ainsi que les vitesses permises dans les différents secteurs.
Pronostic : Un pronostic est une prévision des heures d’arrivée et de départ en tenant compte de la position actuelle du moyen de transport ainsi que des conflits résultant d’un retard et les décisons prévues qui en suivent dans les prochaines x minutes et leurs effets. Pour des prévisions plus loins dans le futur, une méthode plus simple est appliquée.
Moyen de transport : Soit portant la signification « type de véhicule » (train, bateau, tram, bus) ou la signification « système de transport » (transports publics, etc.).
DateTime dans Response : Il’s agit de l’« heure Zoulou » dans tous les cas (c.-à.-d. UTC). Pour obtenir l’heure locale suisse, il faut ajouter deux heures en été, une heure en hiver.

Détails techniques

API Explorer

Autorisation et Open Services

Afin de pouvoir accéder l’API vous avez besoin d’une clé API. Elle peut être obtenue par le portail développeurs.

La clé doit être incluse comme “Authorization” dans le header HTTP.

L’URL pour y accéder

API: https://api.opentransportdata.swiss/trias2020

Clé d’essai : 57c5dbbbf1fe4d000100001842c323fa9ff44fbba0b9b925f0c052d1

En spécifiant le header contenant l’autorisation et Content-Type= „text/XML“ ou „application/XML“

Authorization header

Exemple d’une requête

On spécifie, entre autres, la halte de départ et la halte d’arrivée (numéro DiDok), ainsi que l’heure de départ ou d’arrivée souhaitée (sans indication : départ immédiat). La réponse fournit de données temps réel, si disponibles.

<? xml version="1.0" encoding="UTF-8"?>
<Trias version = "1.1" xmlns="http://www.vdv.de/trias" xmlns:siri="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ServiceRequest>
        <siri:RequestTimestamp>2020-09-30T11:42:03.007Z</siri:RequestTimestamp>
        <siri:RequestorRef>API-Explorer</siri:RequestorRef>
        <RequestPayload>
            <TripRequest>
                <Origin>
                    <LocationRef>
                        <StopPointRef>8500320</StopPointRef>
                    </LocationRef>
                    <DepArrTime>2020-09-30T01:02:03</DepArrTime>
                </Origin>
                <Destination>
                    <LocationRef>
                        <StopPointRef>8500322</StopPointRef>
                    </LocationRef>
                </Destination>
                <Params>
                    <NumberOfResults>1</NumberOfResults>
                    <IncludeTrackSections>true</IncludeTrackSections>
                    <IncludeLegProjection>true</IncludeLegProjection>
                    <IncludeIntermediateStops>true</IncludeIntermediateStops>
                </Params>
            </TripRequest>
        </RequestPayload>
    </ServiceRequest>
</Trias>

La requête est transmise comme body.

Explication détaillée de la requête

Les éléments principaux de la requête :

nom	obligatoire?	description	exemple
Origin	oui	Données spécifiant le lieu de départ	<Origin> <LocationRef> <StopPointRef>8500320</StopPointRef> </LocationRef> <DepArrTime>2016-08-01T09:11:40</DepArrTime> </Origin>
LocationRef	oui		–
StopPointRef	oui	La halte, numéro DiDok	8500320
DepArrTime	non	L’heure de départ ou d’arrivée. Si l’élément manque : l’heure actuelle	2020-08-01T09:11:40
Via	non, plusieurs	Un ou plusieurs lieux via. Les via devront être visités dans la séquence indiquée. Le serveur a la liberté de remplacer une halte via par une autre halte équivalente. Attention : Ne pas implémenté dans le système actuel	–
NoChangeAt	non, plusieurs	Pas de changement à ces haltes Attention : Ne pas implémenté dans le système actuel	–
Destination	oui	Données spécifiant le lieu d’arrivée Même structure que Origin	–
Params	non	… voir la tabelle suivante	–

Params :

nom	obligatoire?	description	exemple
IncludeTrackSections	non	Affichage des TrackSections. Valeur par défaut = true. Implémentation partielle (un seul track), ne pas vraiment intéressant	true
IncludeLegProjection	non	Attention : Ne pas implémenté	true
IncludeIntermediateStops	non	Implémenté, mais il manque l’affichage des intermediate stops.	true
NumberOfResults	non	Nombre des trajets dans la réponse. Valeur par défaut = 3. C’est aussi le nombre minimal, même si une valeur inférieure à 3 a été spécifiée.	20

Les paramètre suivants (définis dans VDV432) n’étaient pas implémentés dans la version précédente de TRIAS. L’état de situation pour TRIAS2020 n’est pas encore suffisamment clair et documenté à l’heure actuelle (octobre 2020). La liste suivante ne correspond donc potentiellement pas à l’état actuel. Une mise à jour est prévue dans les mois à venir.

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.

Explication d’une réponse

Structure d’une réponse :

<? xml version="1.0" encoding="UTF-8"?>
<trias:Trias xmlns:siri="http://www.siri.org.uk/siri" xmlns:trias="http://www.vdv.de/trias" xmlns:acsb="http://www.ifopt.org.uk/acsb" xmlns:ifopt="http://www.ifopt.org.uk/ifopt" xmlns:datex2="http://datex2.eu/schema/1_0/1_0" version="1.1">
    <trias:ServiceDelivery>
        <siri:ResponseTimestamp>2020-09-30T11:25:56Z</siri:ResponseTimestamp>
        <siri:ProducerRef>EFAController10.4.10.25-OJP-EFA01-P</siri:ProducerRef>
        <siri:Status>true</siri:Status>
        <trias:Language>de</trias:Language>
        <trias:CalcTime>72</trias:CalcTime>
        <trias:DeliveryPayload>
            <trias:TripResponse>
                <trias:TripResponseContext>
                    <trias:Situations></trias:Situations>
                </trias:TripResponseContext>
                <trias:TripResult>
                    <trias:ResultId>ID-2BE4715E-B8EA-4550-940F-471B34CA2D60</trias:ResultId>
                    <trias:Trip>
                        <trias:TripId>ID-6A87028D-B0B9-4302-B7B8-7483FC31A0F4</trias:TripId>
                        <trias:Duration>PT15M</trias:Duration>
                        <trias:StartTime>2020-09-30T10:20:00Z</trias:StartTime>
                        <trias:EndTime>2020-09-30T10:35:00Z</trias:EndTime>
                        <trias:Interchanges>0</trias:Interchanges>
                        <trias:Distance>10724</trias:Distance>
                        <trias:TripLeg>
                            <trias:LegId>1</trias:LegId>
                            <trias:TimedLeg>
                                <trias:LegBoard>
                                    <trias:StopPointRef>8572748</trias:StopPointRef>
                                    <trias:StopPointName>
                                        <trias:Text>Stein-Säckingen, Bahnhof</trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:StopPointName>
                                    <trias:PlannedBay>
                                        <trias:Text>C</trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:PlannedBay>
                                    <trias:ServiceDeparture>
                                        <trias:TimetabledTime>2020-09-30T10:20:00Z</trias:TimetabledTime>
                                    </trias:ServiceDeparture>
                                    <trias:StopSeqNumber>1</trias:StopSeqNumber>
                                </trias:LegBoard>
                                <!-- weitere Legs -->
                                <trias:Service>
                                    <trias:OperatingDayRef>2020-09-30</trias:OperatingDayRef>
                                    <trias:JourneyRef>ojp:92033:Y:R:j20:41:37243</trias:JourneyRef>
                                    <trias:LineRef>ojp:92033:Y:R</trias:LineRef>
                                    <trias:DirectionRef>return</trias:DirectionRef>
                                    <trias:Mode>
                                        <trias:PtMode>bus</trias:PtMode>
                                        <trias:BusSubmode>localBus</trias:BusSubmode>
                                        <trias:Name>
                                            <trias:Text>Bus</trias:Text>
                                            <trias:Language>de</trias:Language>
                                        </trias:Name>
                                    </trias:Mode>
                                    <trias:PublishedLineName>
                                        <trias:Text></trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:PublishedLineName>
                                    <trias:OperatorRef>ojp:7000</trias:OperatorRef>
                                    <trias:Attribute>
                                        <trias:Text>
                                            <trias:Text>VELOS: Keine Beförderung möglich</trias:Text>
                                            <trias:Language>de</trias:Language>
                                        </trias:Text>
                                        <trias:Code>A__VN</trias:Code>
                                    </trias:Attribute>
                                    <!-- weitere Attributes -->
                                    <trias:OriginText>
                                        <trias:Text></trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:OriginText>
                                    <trias:DestinationText>
                                        <trias:Text>Laufenburg, Bahnhof</trias:Text>
                                        <trias:Language>de</trias:Language>
                                    </trias:DestinationText>
                                </trias:Service>
                            </trias:TimedLeg>
                        </trias:TripLeg>
                    </trias:Trip>
                </trias:TripResult>
            </trias:TripResponse>
        </trias:DeliveryPayload>
    </trias:ServiceDelivery>
</trias:Trias>

Les éléments de la réponse :

TripResponse: la réponse …
… qui contient des TripResults

Ce qu’on retrouve dans un TripResult:

Trip

nom	obligatoire?	description	exemple
ResultID	oui	Id à usage interne	ID-95725E00-4D45-4651-99A7-3BB4AFFA4E0D
TripID	oui	Id à usage interne	ID-95725E00-4D45-4651-99A7-3BB4AFFA4E0D
Duration	oui	Durée complète en minutes	7
StartTime	oui	L’heure de départ, heure Zoulou	2020-08-01T07:19:00Z
EndTime	oui	L’heure d’arrivée, heure Zoulou	2020-08-01T07:26:00Z
Interchanges	oui	Nombe de changements	0

TripLeg

nom	obligatoire?	description	exemple
LegID	oui	Nunéro courant du Leg Toujours 1 dans l’implémentation des CFF.	1
TimedLeg	oui	VDV431 connait différents types de Legs. L’implémentation actuelle n’utilise que TimedLeg.	–
LegBoard	oui	Le lieu où se trouve le Leg	–
StopPointRef	oui	Numéro Didok	8500320
StopPointName	oui	Le nom associé au numéro DiDok. Attention: La langue doit être DE (allemand).	–
ServiceDeparture	oui	Une structure heure de départ	–
TimetabledTime	oui	L’heure de départ selon l’horaire	2020–08–01T07:19:00Z
EstimatedTime	non	L’heure de départ selon le pronostic. Pour les étapes dans le passé il s’agit soit du dernier pronostic qui a été calculé, soit de données réelles (Ist-Daten).	2020–08–01T07:19:00Z
EstimatedBay	non	Nom du secteur de l’halte où on monte ou descend du véhicule. Selon l’état actuel de planification.	<trias:EstimatedBay> <trias:Text>43</trias:Text> <trias:Language>DE</trias:Language> </trias:EstimatedBay>
Planned Bay	non	Nom du secteur de l’halte où on monte ou descend du véhicule. Selon le dernier pronostic.	<trias:PlannedBay> <trias:Text>43/44</trias:Text> <trias:Language>DE</trias:Language> </trias:PlannedBay>
StopSequenceNumber	oui	Numéro courant du Stop	1
LegIntermediate	non	Même structure que LegBoard, pour une halte intermédiaire. Contient ServiceDeparture et ServiceArrival comme données temporelles.	–
LegAlight	oui	Même structure que LegBoard, pour l’halte d’arrivée. Contient Servicearrival comme seule donnée temporelle.	–
Service	oui	Données concernant les services liée au Leg	–
LegTrack	non	Description géométrique du trajet en détail.	–

Service

Pour une description de la structure “Service” veuillez consulter cette page.

Erreurs / problèmes

La réponse fournit une « ErrorMessage » en cas de problème lors de l’exécution de la requête :

<? xml version="1.0" encoding="UTF-8"?>
<trias:Trias xmlns:siri="http://www.siri.org.uk/siri" xmlns:trias="http://www.vdv.de/trias" xmlns:acsb="http://www.ifopt.org.uk/acsb" xmlns:ifopt="http://www.ifopt.org.uk/ifopt" xmlns:datex2="http://datex2.eu/schema/1_0/1_0" version="1.1">
    <trias:ServiceDelivery>
        <siri:ResponseTimestamp>2020-09-30T13:36:50Z</siri:ResponseTimestamp>
        <siri:ProducerRef>EFAController10.4.10.25-OJP-EFA02-P</siri:ProducerRef>
        <siri:Status>true</siri:Status>
        <trias:Language>de</trias:Language>
        <trias:CalcTime>20</trias:CalcTime>
        <trias:DeliveryPayload>
            <trias:TripResponse>
                <trias:ErrorMessage>
                    <trias:Code>-4000</trias:Code>
                    <trias:Text>
                        <trias:Text>TRIP_NOTRIPFOUND</trias:Text>
                        <trias:Language>de</trias:Language>
                    </trias:Text>
                </trias:ErrorMessage>
            </trias:TripResponse>
        </trias:DeliveryPayload>
    </trias:ServiceDelivery>
</trias:Trias>

Remarques

Important à savoir, surtout pour des développeurs extérieurs :

EstimatedBay et PlannedBay contiennent les informations concernant les voies planifiées par les systèmes. Dans ce contexte, les voies « 12 » et « 12A » sont traitées comme deux voies différentes. EstimatedBay pour la gare de Zürich HB peut être « 41/41 » tandis que plus tard, PlannedBay peut être précisé comme «41 ».
Pour des raisons techniques, le service ne trouve que des liasons directes.
Ne tient pas en compte des métahaltes. Le service trouve un résultat pour la requête Wankdorf à Berne – mais ne trouve pas de résultat pour Wankdorf, Bahnhof àBerne.
Des trajets supprimés sont ignorés (contrairement au cas du StopEvent).

Pour en savoir plus

Informations générales concernant l’autorisation et les clés API : Developer Dashboard
Documentation TRIAS : https://www.vdv.de/ip-kom-oev.aspx
Le service TRIAS (PDF) : https://www.vdv.de/431-2sds-v1.1.pdfx
XSD: https://www.vdv.de/trias-xsd-v1.1.zipx?forced=true