Référentiel GTFS¶
Tout part de là. Le GTFS décrit l'offre théorique du réseau — lignes, arrêts, tracés, calendriers, horaires — et c'est lui qui donne leur identité aux courses que l'API expose ensuite.
Un groupe conserve plusieurs GTFS¶
Un GTFS n'est pas importé une fois pour toutes. Un réseau change d'offre à chaque saison, à chaque travaux, à chaque adaptation de desserte. Ce n'est pas une nouvelle version d'un GTFS existant : c'est un nouveau GTFS, avec un nouvel identifiant. Le groupe accumule donc des GTFS distincts, chacun publié pour sa plage de validité.
La conséquence pratique est importante : une date détermine le GTFS en vigueur. Demander les horaires d'une course sans savoir de quel GTFS elle relève n'a pas de sens dès qu'on sort de la journée courante.
| Endpoint | Rôle |
|---|---|
GET /api/v4/groups/<group_id>/gtfs |
Liste les GTFS du groupe |
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id> |
Décrit un GTFS et sa validité |
GET /api/v4/groups/<group_id>/history/gtfs-active |
Donne le GTFS en vigueur à une date passée |
Pour une intégration qui travaille sur des données historiques, le troisième endpoint est le point d'entrée : il évite de reconstituer soi-même la correspondance entre une date et un GTFS.
Le cycle de vie d'un GTFS¶
Un GTFS importé n'entre pas en service immédiatement. Il est d'abord validé, puis publié ; l'archivage le retire du service sans le détruire, de sorte que les données produites pendant qu'il était actif restent interprétables.
C'est pourquoi un GTFS archivé reste consultable : les courses réalisées il y a six mois se rattachent au GTFS qui était alors en vigueur, et non à celui d'aujourd'hui.
| Endpoint | Rôle |
|---|---|
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id>/validate |
Donne le rapport de validation d'un GTFS |
Ce que le référentiel contient¶
Trois objets du GTFS reviennent constamment dans l'API, définis dans le glossaire :
- gtfs — le GTFS lui-même ;
- trips — les courses prévues ;
- stop_times — leurs horaires de passage aux arrêts.
Les lignes, arrêts et tracés existent aussi dans le référentiel, mais l'API publique les expose à travers les courses plutôt que comme des collections propres : on lit les arrêts d'une course, pas le catalogue des arrêts.
Et ensuite¶
Une fois le GTFS en vigueur connu, on peut désigner une course sans ambiguïté — c'est l'objet de la page Courses.