Meilleures pratiques GTFS Realtime¶
Introduction¶
Il s'agit de pratiques recommandées pour décrire les informations sur les transports publics en temps réel dans le format de données GTFS Realtime.
Structure du document¶
Les pratiques recommandées sont organisées en deux sections principales
- Recommandations de pratiques organisées par message: Les recommandations sont organisées par message et par champ dans le même ordre que celui décrit dans la référence officielle GTFS Realtime.
- Recommandations pratiques organisées par cas: Dans certains cas particuliers, tels que le service basé sur la fréquence (par opposition au service basé sur l'horaire), il peut être nécessaire d'appliquer les pratiques à plusieurs messages et champs ainsi qu'aux données GTFS Schedule Schedule correspondantes. Ces recommandations sont regroupées dans cette section.
Publication des flux et pratiques générales¶
- Les flux doivent être publiés à une url publique et permanente.
- L'url doit être directement accessible sans qu'il soit nécessaire de se connecter pour accéder au flux. Si vous le souhaitez, vous pouvez utiliser des clés API, mais l'enregistrement des clés API doit être automatisé et accessible à tous.
- Maintenir des identifiants persistantsid champsid ) dans un flux GTFS Realtime (par exemple,
FeedEntity.id
,VehicleDescriptor.id
,CarriageDetails.id
) entre les itérations du flux. - Les flux GTFS Realtime doivent être actualisés au moins une fois toutes les 30 secondes, ou lorsque les informations représentées dans le fluxPosition d'un vehicle) changent, selon la fréquence la plus élevée. Les VehiclePositions ont tendance à changer plus fréquemment que les autres entités de flux et doivent être actualisées aussi souvent que possible. Si le contenu n'a pas changé, le flux doit être mis à jour avec un nouveau
FeedHeader.timestamp
indiquant que les informations sont toujours pertinentes à partir de ce timestamp. - Les données contenues dans un flux GTFS Realtime ne doivent pas être antérieures à 90 secondes pour les mises à jour des trip et les positions des vehicle, ni à 10 minutes pour les alertes de service. Par exemple, même si un producteur rafraîchit continuellement le
FeedHeader.timestamp
timestamp toutes les 30 secondes, l'âge des VehiclePositions dans ce flux ne doit pas être supérieur à 90 secondes. - Le serveur hébergeant les données GTFS Realtime doit être fiable et renvoyer systématiquement des réponses codées protobuf valides. Moins de 1 % des réponses doivent être invalides (erreurs de protobuf ou erreurs d'extraction).
- Le serveur web qui héberge les données GTFS Realtime doit être configuré pour signaler correctement la date de modification du fichier (voir HTTP/1.1 - Request for Comments 2616, section 14.29) afin que les consommateurs puissent utiliser l'header HTTP
If-Modified-Since
. Cela permet aux producteurs et aux consommateurs d'économiser de la bande passante en évitant de transférer des contenus de flux qui n'ont pas été modifiés. - Les flux devraient fournir un contenu de flux codé par tampon de protocole par défaut lorsqu'ils sont interrogés via une requête HTTP à l'url donnée - les consommateurs ne devraient pas avoir besoin de définir des en-têtes HTTP acceptés spéciaux pour recevoir un contenu codé par tampon de protocole.
- En raison de la façon dont les tampons de protocole codent les valeurs facultatives, avant de lire les données d'un flux GTFS Realtime, les consommateurs doivent vérifier la présence de valeurs à l'aide des méthodes
hasX()
générées par le tampon de protocole avant d'utiliser cette valeur et ne doivent utiliser la valeur que sihasX()
est vrai (oùX
est le nom du champ). SihasX()
renvoiefalse
, la valeur par défaut pour ce champ définie dans la valeurGTFS
.proto doit être prise en charge. Si le consommateur utilise la valeur sans vérifier au préalable la méthodehasX()
, il peut lire des données par défaut qui n'ont pas été publiées intentionnellement par le producteur. - Les flux doivent utiliser HTTPS au lieu de HTTP (sans cryptage) pour garantir l'intégrité des flux.
- Les flux doivent couvrir la grande majorité des voyages inclus dans l'ensemble de données statiques complémentaires GTFS. En particulier, ils doivent inclure des données sur les zones urbaines à forte densité et à fort trafic et sur les routes très fréquentées.
Recommandations de pratiques organisées par message¶
FeedHeader¶
Nom du champ | Recommandation |
---|---|
gtfs_realtime_version |
La version actuelle est "2.0". Tous les flux GTFS Realtime devraient être "2.0" ou plus, car la première version de GTFS Realtime n'exigeait pas tous les champs nécessaires pour représenter correctement les diverses situations de transit. |
timestamp |
Cet timestamp ne doit pas diminuer entre deux itérations séquentielles du flux. |
Cette valeur d'timestamp doit toujours changer si le contenu du flux change - le contenu du flux ne doit pas changer sans mettre à jour l'header. timestamp .Erreurs courantes - S'il y a plusieurs instances de flux GTFS Realtime derrière un équilibreur de charge, chaque instance peut extraire des informations de la source de données en temps réel et les publier aux consommateurs de manière légèrement désynchronisée. Si un consommateur GTFS Realtime fait deux demandes consécutives, et que chaque demande est servie par une instance de flux GTFS Realtime différente, le même contenu de flux peut potentiellement être renvoyé au consommateur avec des horodatages différents. Solution possible - Les producteurs doivent fournir un en-tête Last-Modified et les consommateurs doivent transmettre leur header HTTP le plus récent. If-Modified-Since header éviter de recevoir des données périmées.Solution possible - S'il n'est pas possible d'utiliser les en-têtes HTTP, des options telles que les sessions collantes peuvent être utilisées pour s'assurer que chaque consommateur est dirigé vers le même serveur producteur. |
FeedEntity¶
Toutes les entités ne doivent être retirées d'un flux GTFS Realtime que lorsqu'elles ne sont plus pertinentes pour les utilisateurs. Les flux sont considérés comme apatrides, ce qui signifie que chaque flux reflète l'état complet du système de transittime. Si une entity est fournie dans une instance de flux mais qu'elle est abandonnée dans une mise à jour ultérieure du flux, il faut supposer qu'il n'y a pas d'informationtime pour cette entity.
Nom du champ | Recommandation |
---|---|
id |
Doit rester stable pendant toute la durée du trip |
TripUpdate¶
Directives générales pour les annulations de trip:
- Lors de l'annulation de trajets sur plusieurs jours, les producteurs doivent fournir des TripUpdates référençant les
trip_ids
et lesstart_dates
donnés commeCANCELED
ainsi qu'une Alert avecNO_SERVICE
référençant les mêmestrip_ids
etTimeRange
qui peut être montrée aux coureurs expliquant l'annulation (par exemple, DETOUR). - Si aucun arrêt d'un trip n'est visité, le trip doit être
CANCELED
au lieu d'avoir toutes lesmises à jour des heures d'arrêt
marquées commeSKIPPED
.
Nom du champ | Recommandation |
---|---|
trip |
Se référer à message TripDescriptor. |
Si séparé VehiclePosition et TripUpdate sont fournis, TripDescriptor et VehicleDescriptor l'appariement des valeurs d'id doit correspondre entre les deux flux.Par exemple, un VehiclePosition entity a vehicle_id:A et trip_id:4 alors le correspondant TripUpdate l'entity devrait aussi avoir vehicle_id:A et trip_id:4 . Si un TripUpdate l'entity a trip_id:4 et tout vehicle_id autre que 4, il s'agit d'une erreur. |
|
vehicle |
Se référer à message VehicleDescriptor. |
Si des VehiclePosition et TripUpdate des flux séparés sont fournis, TripDescriptor et VehicleDescriptor L'appariement des valeurs d'id doit correspondre entre les deux flux.Par exemple, une VehiclePosition l'entity a vehicle_id:A et trip_id:4 alors l'entité correspondante TripUpdate l'entity devrait aussi avoir vehicle_id:A et trip_id:4 . S'il y en a TripUpdate l'entity a trip_id:4 et n'importe quel vehicle_id autre que 4, il s'agit d'une erreur. |
|
stop_time_update |
stop_time_updates pour un trip_id doit être strictement ordonné par ordre croissant stop_sequence et aucun stop_sequence ne doit être répété. |
Pendant le trip, tous les messages TripUpdates devraient inclure au moins un stop_time_update avec une time arrival ou de departure prévue dans le futur. Notez que la spécification GTFS Realtime dit que les producteurs ne devraient pas laisser tomber un StopTimeUpdate s'il se réfère à un arrêt avec une time arrival SCHEDULED dans le futur pour le trip donné (c'est-à-dire que le vehicle a passé l'arrêt avant l'heure prévue), car sinon il sera conclu qu'il n'y a pas de mise à jour pour cet arrêt. |
|
timestamp |
Doit refléter l'time cette prédiction pour ce trip a été mise à jour. |
delay |
TripUpdate.delay doit représenter l'écart par rapport au programme, c'est-à-dire la valeur passée observée de l'avance ou du retard du vehicle par rapport au programme. Les prédictions pour les arrêts futurs doivent être fournies par le biais de StopTimeEvent.delay ou StopTimeEvent.time . |
TripDescriptor¶
Si des flux séparés VehiclePosition
et TripUpdate
sont fournis, l'appariement des valeurs d id TripDescriptor et VehicleDescriptor doit correspondre entre les deux flux.
Par exemple, si une entity VehiclePosition
possède un Vehicle_id:A
et un trip_id
:4, l'entity TripUpdate
correspondante doit également posséder un Vehicle_id:A
et un trip_id
:4.
Nom du champ | Recommandation |
---|---|
schedule_relationship |
Le comportement des ADDED trips n'est pas spécifié et l'utilisation de cette énumération n'est pas recommandée. |
VehicleDescriptor¶
Si des flux VehiclePosition
et TripUpdate
distincts sont fournis, l'appariement des valeurs TripDescriptor et VehicleDescriptor id doit correspondre entre les deux flux.
Par exemple, si l'entity VehiclePosition
possède Vehicle_id:A
et trip_id
:4, l'entity TripUpdate
correspondante doit également posséder Vehicle_id:A
et trip_id
:4.
Nom du champ | Recommandation |
---|---|
id |
Devrait identifier un vehicle de façon unique et stable pendant toute la durée du trip. |
StopTimeUpdate¶
Nom du champ | Recommandation |
---|---|
stop_sequence |
Fournir stop_sequence dans la mesure du possible, car il correspond sans ambiguïté à une time arrêt GTFS dans le format stop_times.txt contrairement à stop_id qui peut se produire plus d'une fois au cours d'un trip (par exemple, un itinéraire en boucle). |
arrival |
les temps d'arrival entre des arrêts séquentiels doivent augmenter - ils ne doivent pas être identiques ou diminuer. |
arrival time (spécifié en StopTimeEvent) doit être antérieure au departure time pour le même arrêt si une escale ou un time séjour est prévu. time doit être la même que le departure time . |
|
departure |
les heures dedeparture entre des arrêts séquentiels doivent augmenter - elles ne doivent pas être identiques ou diminuer. |
Ledeparture time (spécifiée dans StopTimeEvent) doit être identique à l'arrival time pour le même arrêt s'il n'y a pas d'escale ou de time d'attente. time doit être postérieur à l'arrival time . |
StopTimeEvent¶
Nom du champ | Recommandation |
---|---|
delay |
Si seulement delay est fourni dans un stop_time_update arrival ou departure (et non time ), alors le GTFS stop_times.txt doit contenir arrival_times et/ou departure_times pour ces arrêts correspondants. A delay dans le flux en temps réel n'a aucun sens si vous ne disposez pas d'une time à laquelle l'ajouter dans le GTFS. stop_times.txt fichier. |
VehiclePosition¶
Voici les champs qu'il est recommandé d'inclure dans un flux VehiclePostions pour fournir aux consommateurs des données de haute qualité (par exemple, pour générer des prédictions)
Nom du champ | Remarques |
---|---|
entity.id |
Devrait être maintenu stable pendant toute la durée du trip |
vehicle.timestamp |
Il est fortement recommandé de fournir l'timestamp auquel la Position vehicle a été mesurée. Sinon, les consommateurs doivent utiliser l'timestamp message, ce qui peut donner des résultats trompeurs pour les usagers lorsque le dernier message a été mis à jour plus fréquemment que la Position individuelle. |
vehicle.vehicle.id |
Devrait identifier un vehicle de manière unique et stable pendant toute la durée du trip. |
Position¶
La Position vehicle doit se situer à moins de 200 mètres des données GTFS shapes.txt
pour le trip en cours, à moins qu'il n'y ait une Alert avec l'Effect DETOUR
pour ce trip_id
.
Alert¶
Directives générales pour les alertes :
- Lorsque
trip_id
etstart_time
sont dans l'intervalleexact_time=1
,start_time
doit être postérieur au début de l'intervalle d'un multiple exact deheadway_secs
. - En cas d'annulation de trajets sur plusieurs jours, les producteurs doivent fournir des TripUpdates référençant les
trip_ids
et lesstart_dates
donnés commeCANCELED
ainsi qu'une Alert avecNO_SERVICE
référençant les mêmestrip_ids
etTimeRange
qui peut être montrée aux usagers pour expliquer l'annulation (par exemple, DETOUR). - Si une Alert affecte tous les arrêts d'une ligne, utilisez une Alert basée sur la ligne plutôt qu'une Alert basée sur l'arrêt. N'appliquez pas l'Alert à chaque arrêt de la ligne.
- Bien qu'il n'y ait pas de limite de caractères pour les alertes de service, les usagers du transport en commun consultent souvent les alertes sur des appareils mobiles. Soyez concis.
Nom du champ | Recommandation |
---|---|
description_text |
Utilisez des sauts de ligne pour rendre votre Alert service plus facile à lire. |
Recommandations pratiques classées par cas d'utilisation¶
Trajets basés sur la fréquence¶
Un trip basé sur la fréquence ne suit pas un horaire fixe mais tente de maintenir des intervalles de passage prédéterminés. Ces trajets sont indiqués dans GTFS frequency.txt en définissant exact_times=0
ou en omettant le champ exact_times
(notez que les trajets exact_times=1
ne sont PAS des trajets basés sur la fréquence - frequencies.txt
avec exact_times=1
est simplement utilisé comme une méthode pratique pour stocker les trajets basés sur les horaires d'une manière plus compacte). Il existe plusieurs bonnes pratiques à garder à l'esprit lors de la construction de flux GTFS Realtime pour les trajets basés sur la fréquence.
-
Dans TripUpdate.StopTimeUpdate, l'StopTimeEvent pour l'
arrival
et ledeparture
ne doit pas contenir dedelay
car les trajets basés sur la fréquence ne suivent pas un horaire fixe. Au lieu de cela, l'time
doit être fournie pour indiquer les prévisions d'arrival. -
Comme l'exige la spécification, lorsque vous décrivez un
trip
dans TripUpdate ou VehiclePosition en utilisant TripDescriptor, vous devez fournir tous les élémentstrip_id
,start_time
etstart_date
. De plus,schedule_relationship
doit êtreUNSCHEDULED
.
(par exemple, les trajets de renforcement).
A propos de ce document¶
Objectifs¶
Les objectifs du maintien des meilleures pratiques GTFS Realtime sont les suivants :
- Améliorer l'expérience de l'utilisateur final dans les applications de transport public.
- Faciliter le déploiement et la mise à l'échelle des applications, produits et services par les développeurs de logiciels.
Comment proposer ou modifier les meilleures pratiques GTFS Realtime publiées.¶
Les applications et les pratiques GTFS évoluent, et il est donc possible que ce document doive être modifié de time en time. Pour proposer une modification de ce document, ouvrez une demande de retrait dans le dépôt GitHub GTFS Realtime Best Practices et préconisez le changement.
Liens vers ce document¶
Veuillez établir un lien ici afin de fournir aux producteurs d'aliments pour animaux des conseils pour la formation correcte des données GTFS Realtime. Chaque recommandation individuelle a un lien d'ancrage. Cliquez sur la recommandation pour obtenir l'url du lien d'ancrage dans la page.
Si une application GTFS Realtime formule des exigences ou des recommandations concernant les pratiques en matière de données GTFS Realtime qui ne sont pas décrites ici, il est recommandé de publier un document contenant ces exigences ou recommandations pour compléter ces meilleures pratiques communes.