Réseau¶
Le référentiel théorique : ce que le réseau prévoit de faire. Il vient du GTFS importé et ne change qu'à la publication d'un nouveau GTFS.
gtfs¶
GTFS — le jeu de données décrivant l'offre théorique du réseau : lignes, arrêts, tracés, calendriers et horaires. Format standard du secteur, il est importé dans le groupe puis publié pour devenir la référence en vigueur.
Identifiant <gtfs_id>. Un groupe conserve plusieurs GTFS : celui en service, les précédents, et ceux à venir. Ce ne sont pas des versions d'un même GTFS — quand l'offre change, un nouveau GTFS est importé, avec un nouvel identifiant. Chacun est publié pour une plage de validité, si bien qu'une date donnée détermine le GTFS en vigueur. Les courses, horaires aux arrêts et fréquences appartiennent à un GTFS précis — c'est pourquoi une course se désigne par son identifiant et son gtfs_id.
| 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>/gtfs/<gtfs_id>/validate |
Donne le rapport de validation |
Le cycle de vie d'un GTFS se lit dans ces trois appels : un GTFS importé reste inactif jusqu'à sa publication, et l'archivage le retire du service sans le détruire.
| Endpoint | Rôle |
|---|---|
POST /api/v4/groups/<group_id>/gtfs |
Importe un nouveau GTFS |
POST /api/v4/groups/<group_id>/gtfs/<gtfs_id>/publish |
Met le GTFS en service |
POST /api/v4/groups/<group_id>/gtfs/<gtfs_id>/archive |
Retire le GTFS du service |
trips¶
Course — un trajet prévu sur une ligne, avec son itinéraire et ses horaires de passage. C'est l'objet central de l'exploitation : on planifie des courses, on les affecte, on les suit, et on mesure leur réalisation.
Identifiant <trip_id>, qui vient du GTFS. Une course seule ne suffit pas à désigner un trajet réel : il faut le triplet identifiant de course, date de service et gtfs_id, puisqu'un identifiant de course n'est unique qu'au sein de son GTFS et que la course se répète chaque jour de circulation. Les trois composantes forment une clé unique : le triplet désigne une et une seule exécution de course.
| 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>/export/trips |
Exporte les courses réalisées au format CSV |
stop_times¶
Horaire aux arrêts — les heures de passage prévues d'une course à chacun des arrêts qu'elle dessert, dans l'ordre. C'est ce qui permet de dire qu'un véhicule est en avance ou en retard : l'écart se mesure toujours contre l'horaire théorique de l'arrêt concerné.
Pas d'identifiant propre : un horaire se désigne par sa course et le rang de l'arrêt dans la séquence.
| Endpoint | Rôle |
|---|---|
GET /api/v4/groups/<group_id>/stop_times |
Donne les horaires prévus aux arrêts |
Les horaires réellement observés sont conservés à part, décrits dans l'entrée history.
frequencies¶
Fréquence — un mode de description de l'offre où une course n'est pas donnée par ses horaires exacts mais par un intervalle de passage sur une plage horaire, par exemple un bus toutes les dix minutes de 7 h à 9 h. Notion standard du GTFS, employée sur les lignes à forte cadence.
Pas d'identifiant propre : une fréquence appartient à une course et à une plage horaire.
Ces données sont servies à l'application Pysae Driver et ne sont pas publiées dans le spec public.
| Endpoint | Rôle |
|---|---|
GET /api/v4/groups/<group_id>/frequencies |
Donne les fréquences déclarées |
planning¶
Planification — l'affectation prévisionnelle des moyens aux courses : quel conducteur et quel véhicule assurent quelle course, à quelle date. C'est le pont entre le référentiel théorique et les moyens réels du groupe.
Pas d'identifiant propre : une ligne de planification se désigne par sa course et sa date. Elle référence un conducteur, un véhicule, et éventuellement un bloc — la suite de courses enchaînées par un même véhicule.
| Endpoint | Rôle |
|---|---|
GET /api/v4/groups/<group_id>/planning |
Donne l'affectation prévue sur une période |
PUT /api/v4/groups/<group_id>/planning |
Enregistre l'affectation prévue |
La planification est une prévision. Ce qui a réellement été assuré se lit dans le service de conduite, décrit dans l'entrée duties.