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 trip_events et 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

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.