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.

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.

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 partage se règle depuis les applications Pysae, par l'opérateur : PUT /api/v4/groups/<group_id>/gtfs/<gtfs_id>/metadata avec {"public_download": true}. Il sert aux fichiers préparés pour un portail open data sans être mis en service. Un GTFS publié reste téléchargeable quel que soit ce réglage.

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.

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.

L'import et les transitions d'état sont réservés aux applications Pysae : POST /api/v4/groups/<group_id>/gtfs, puis .../publish, .../archive et .../restore.

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.