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> |
Télécharge l'archive zip d'un GTFS |
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.
Consulter et télécharger un GTFS sans authentification¶
La liste des GTFS d'un groupe est publique : elle montre aussi les offres à venir et les brouillons. Un appel anonyme n'y reçoit ni l'auteur de la dernière modification (mod_user), ni le rapport de validation (validation), ni l'échec d'une publication programmée (publication_failed) : ces champs demandent un rôle de lecture sur le groupe. Les archives, elles, se téléchargent sans compte dans deux cas.
| Endpoint | Accès anonyme |
|---|---|
GET /api/v4/groups/<group_id>/gtfs |
Toujours : liste les GTFS du groupe, y compris les offres à venir et les brouillons |
GET /api/v4/groups/<group_id>/gtfs/pub |
Toujours : c'est le GTFS en vigueur, l'URL stable à donner à un portail open data |
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id> |
Si ce GTFS a déjà été publié, ou si l'opérateur l'a partagé pour le téléchargement public |
Tout autre GTFS — brouillon, offre programmée, import jamais partagé — demande un rôle de lecture sur le groupe ; un appel anonyme reçoit 403 NO_ROLE, y compris pour un identifiant inconnu. Le champ public_download d'un GTFS indique s'il a été partagé.
Les deux endpoints d'archive répondent avec un en-tête ETag et un en-tête Last-Modified, et acceptent les requêtes conditionnelles : renvoyez l'ETag dans If-None-Match (ou la date dans If-Modified-Since) et une archive inchangée reçoit un 304 Not Modified vide, sans être reconstruite. If-None-Match est prioritaire quand les deux en-têtes sont envoyés. L'ETag change aussi quand une équipe du groupe est renommée, ce que Last-Modified ne reflète pas.
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 |
La validation s'appuie sur un service de contrôle dédié. S'il ne répond pas à temps, l'appel renvoie 504 GTFS_VALIDATOR_TIMED_OUT ; s'il est injoignable ou répond en erreur, 502 GTFS_VALIDATOR_UNAVAILABLE. Dans les deux cas le GTFS n'est pas en cause : le rapport reste en attente et l'appel peut être relancé plus tard.
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.