Courses¶
La course est l'objet central de l'exploitation. C'est aussi celui qui se désigne le moins simplement : un identifiant de course, seul, ne suffit jamais.
Le triplet d'identification¶
Une course se désigne par trois informations :
| Élément | Pourquoi il est nécessaire |
|---|---|
| L'identifiant de course | Il vient du GTFS et nomme le trajet dans le plan de transport |
| La date de service | La même course circule chaque jour d'exploitation |
Le gtfs_id |
Un identifiant de course n'est unique qu'au sein de son GTFS ; il faut donc savoir de quel GTFS il relève |
Omettre la date revient à demander « la course 4218 » sans dire quel jour ; omettre le gtfs_id revient à demander ses horaires sans dire selon quel plan de transport. Les deux omissions produisent des résultats plausibles mais faux — c'est le piège le plus coûteux à l'intégration.
Les trois composantes forment une clé unique : le triplet désigne une et une seule exécution de course, il n'apparaît jamais en double.
Prévu et réalisé¶
Une course porte les deux temps du système à la fois.
| Où ça se lit | Ce que ça donne | |
|---|---|---|
| Prévu | Les horaires du référentiel, voir stop-times | L'heure à laquelle la course devait passer à chaque arrêt |
| Réalisé | Les remontées des appareils, voir history | L'heure à laquelle elle est effectivement passée |
L'avance-retard n'est pas une donnée stockée à part : c'est l'écart entre ces deux lectures, arrêt par arrêt. La ponctualité en est l'agrégat sur une période.
| Endpoint | Rôle |
|---|---|
GET /api/v4/groups/<group_id>/trips |
Liste les courses sur une période |
GET /api/v4/groups/<group_id>/trips/<trip_id> |
Décrit une course |
GET /api/v4/groups/<group_id>/stop-times |
Donne les horaires prévus aux arrêts |
Passages observés aux arrêts¶
Une arrivée correspond à l'entrée dans l'état arrêté ; les remontées suivantes pendant l'attente ne créent pas de nouvelle arrivée. Un départ correspond à la sortie de cet état vers l'arrêt suivant, même si des arrêts intermédiaires ont été sautés. Les oscillations GPS vers le même arrêt et les états résiduels d'une course précédente ne confirment pas un départ.
Si plusieurs passages sont observés au même arrêt, celui dont l'écart absolu à l'horaire théorique est le plus faible est retenu. L'historique de ponctualité, le suivi des courses v5 et le flux GTFS-RT appliquent cette même règle. Cela peut corriger les statistiques de ponctualité v5 et les horaires publiés en GTFS-RT, notamment lorsqu'une dérive GPS avait fait apparaître un départ en avance au terminus.
Les anciennes courses v5 restent lisibles avec leur déduction historique des départs. Elles ne sont pas recalculées rétroactivement. La migration backfill_first_stop_departures peut corriger les départs du premier arrêt depuis les passages d'historique, en retenant le plus proche du théorique ; elle n'effectue pas de rejeu complet des courses.
Ce que l'exploitant peut modifier¶
Le référentiel n'est pas réécrit à chaque aléa. Une perturbation se traduit par une modification de course qui se superpose au théorique sur une période : arrêt supprimé, déplacé, ajouté, course déviée ou annulée. Voir trip-updates.
Un intégrateur ne lit pas ces modifications directement — elles ne sont pas publiées dans le spec public — mais il en voit l'effet dans les flux temps réel décrits page suivante, et dans les courses réalisées.
Les versions v4 et v5¶
v4 est la version par défaut de l'API et celle que ce guide emploie.
v5 réécrit la lecture des courses sur les événements remontés par les appareils plutôt que sur un état recalculé : la course réalisée se reconstitue depuis la suite des faits observés. Ce mode s'active groupe par groupe, et ses endpoints ne sont pas publiés dans le spec public à ce jour — une intégration externe travaille donc en v4.
| Endpoint | Rôle |
|---|---|
GET /api/v5/groups/<group_id>/trips |
Liste les courses reconstruites depuis les événements |
Et ensuite¶
Reste à comprendre d'où viennent les remontées qui alimentent le réalisé — c'est l'objet de la page Temps réel.