Aller au contenu

Affichage des départs/arrivées

(TRIAS StopEventRequest)

L’affichage des départ / arrivées est un open service (API). Il correspond au service « StopEvent » de VDV431.

Nouvelle interface (TRIAS2020) : Cette interface s’inspire directement du nouveau et puissant protocole OJP. Pour en savoir plus – cette page décrit les différences et les nouveautés. Les clés API existantes resteront valides, il suffit de référencer la nouvelle URL.

Description technique

L’API d’affichage des départs/arrivées permet de consulter les départs/arrivées à une halte pour une heure donnée. Des informations en temps réel sont fournies pour les haltes dotées de cette fonction..

Comme donnée d’entrée de base il faut spécifier une halte. Elle peut être trouvée en consultant la liste des gares, p.ex.

A noter: il n’est pas possible d’utiliser des métahaltes.  Cela veut dire, pour l’exemple du «point of interest» Bern, Wankdorf il faut utiliser les haltes suivantes :

  • 8516161, Bern Wankdorf
  • 8590129, Bern Wankdorf, Bahnhof
  • 8595543, Bern Wankdorf, Bahnhof Nord

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

Cette requête est transmise comme body.

Explication détaillée de la requête

La requête contient deux éléments principaux et des paramètres optionnels.

nom obligatoire? description
exemple
StopPointRef oui (*) Le code d’une halte – retrouvé de DiDok ou de a liste des gares 8507000
DepArrTime non Contient l’heure d’arrivée ou de départ (voir également le paramètre StopEventType). Pas d’accès à des données en dehors de -1 à +24h. Si cet élément n’est pas inclus, l’heure actuelle est prise en compte. On n’utilise pas d’heure Zoulou ici.

Les secondes sont obligatoires.

2020-06-27T13:34:00
Params non Les paramètres de la requête. voir la tabelle suivante …

 

Params – les autres paramètres :

nom obligatoire? description exemple
NumberOfResults non Valeur par défaut 10, maximum 40 20
StopEventType oui Deux valeurs possibles : departure/ arrival. departure
IncludePreviousCalls non Inclure des haltes avant la halte en question ? true/false

Valeur par défaut : true

false
IncludeOnwardCalls non Inclure des haltes avant la halte en question ? true/false

Valeur par défaut : true

false
IncludeRealtimeData non Incluser des données temps réel ? true/false

Valeur par défaut : false

false

 

Explication d’une réponse

La réponse est structurée de manière suivante :

 

Les éléments d’un « StopEvent » :

  • PreviousCall: les haltes qui précèdent la halte actuelle
  • ThisCall: halte actuelle
  • OnwardCall: les haltes qui suivent la halte actuelle
  • Service: informations concernant le trajet / voyage

On obtient le trajet complet, de la halte du départ jusqu’à la halte d’arrivée.

 

Nouveautés TRIAS2020:

La réponse fournit les éléments additionnels suivants :

  • « CalcTime »
  • « StopEventResultContex » et « Situations » (TODO: description)
  • « EstimatedTime » non seulement pour « ThisCall », mais maintenant aussi pour « PreviousCall » et « OnwardCall »

« MoreData » n’existe plus car obsolète, toutes les données sont envoyées en une fois.

 

PreviousCall / This Call / OnwardCall

PreviousCall:

ThisCall

OnwardCall:

nom obligatoire? description exemple
StopPointRef oui Code d’une halte
TimetabledTime oui L’heure selon l’horaire. Attention : heure Zoulou 2020-08-18T02:54:00Z
Estimatedtime non L’heure selon pronostic. Attention : « Estimatedtime » n’est disponible que pour des trajets disposant de données temps réel, et exclusivement pour « ThisCall ». « Estimatedtime » peut être égale à « Timetabledtime » si aucune déviation de l’horaire ne s’annonce.

Pour les étapes déjà parcourus (« PreviousCall ») il s’agit soit des pronostics, soit des heures observées (Ist-Daten, données réelles). La réponse ne fournit pas d’indication dans quel des deux cas on se trouve.

2020-08-18T02:54:40Z
PlannedBay non La voie prévue selon l’horiare
EstimatedBay non La voie prévue selon pronostic 12A
StopSequenceNumber non La séquence des haltes est numérotée 3

Service

La structure « Service » est traitée sur la page suivante : Service (VDV 431)

Erreurs / problèmes

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

 

Commentaires

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

  • Les haltes prennent la forme d’un numéro DiDok. Il est donc nécessaire de consulter le fichier DiDok ou la liste des gares. Le numéro DiDok peut être recherché par nom ou par coordonnées géographiques.
  • Les métahaltes ne sont pas prises en compte.
  • Il est possible d’indiquer l’heure d’arrivée ou de départ.
  • Il n’est pas possible de faire une requête pour une localité précise faisant partie d’une halte (Steig, Mast, Kante).

 

CarPostal SA comme cas spécial

La mise à disposition des données horaires de CarPostal SA s’effectue sous la direction de CarPostal Suisse SA. Une particularité est des numéros de lignes appartenant à plusieurs lignes (se trouvant dans des régions différentes, servi par des entreprises différentes). Cela et le fait qu’ils existent des haltes (numéros DiDok) desservies par plusieurs lignes, peut faire apparaitre des problèmes au niveau du « DestinationText » dans certains cas. Cela va être résolu avec de la réalisation de KUBUS et l’importation des données HRDF dans le système central open data.

Entretemps, la solution suivante est conseillée :

Lors de l’importation des données HRDF, déactiver dans DIVA le flag „Zugnummer statt Fahrtschlüssel“ (numéro du train au lieu de la clé trajet) pour la ligne en question. En conséquence, la valeur JourneyRef changera dans les interfaces TRIAS (GTFS n’est pas touché). LineRef et PublishedLineName, utilisés pour l’affichage de la ligne, resteront inchangés.

 

Pour en savoir plus