Aller au contenu

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.