Glossaire des entités¶
L'API manipule les objets métier d'un réseau de transport : le référentiel théorique importé du GTFS, les moyens engagés pour l'exploiter, ce qui se passe réellement sur le terrain, et ce qu'on en mesure. Ce glossaire définit chacun de ces objets — son rôle, son identifiant, ses relations et les endpoints qui l'exposent.
Chaque entrée porte le nom de l'entité tel qu'il apparaît comme tag dans le spec OpenAPI, afin que la référence technique et cette documentation désignent la même chose. Le terme métier employé par les équipes, en français et en anglais, ouvre chaque entrée.
Les six familles¶
| Famille | Ce qu'elle regroupe |
|---|---|
| Organisation | Qui utilise l'API et pour quel périmètre : groupe, équipes, utilisateurs, rôles, clés d'API |
| Réseau | Le référentiel théorique : GTFS, courses, horaires aux arrêts, fréquences, planification |
| Flotte | Les moyens engagés : conducteurs, véhicules, appareils, dépôts, services de conduite |
| Exploitation | Ce qui se passe en ligne : événements de course, modifications, suivi, mouvements, zones dangereuses |
| Communication | Ce qui est diffusé : alertes, messages, notifications, urgences, téléphonie, GTFS-RT, SIRI |
| Mesure | Ce qu'on en tire : kilomètres, ponctualité, comptage voyageurs, statistiques, historiques |
Le groupe, périmètre de tout appel¶
Presque tous les endpoints sont préfixés par /groups/<group_id>. Le groupe est le réseau exploité : il porte ses propres données, et une même donnée n'existe jamais en dehors d'un groupe. Un appel commence donc toujours par savoir sur quel groupe il porte. Voir l'entrée groups.
Théorique et réalisé¶
Deux notions se ressemblent et ne doivent pas être confondues :
- le théorique décrit ce qui est prévu — il vient du GTFS importé et ne change qu'à la publication d'un nouveau GTFS ;
- le réalisé décrit ce qui s'est produit — il naît des remontées des appareils des conducteurs pendant le service.
Une course est théorique ; son exécution un jour donné est réalisée. La plupart des entités de la famille Réseau relèvent du théorique, celles des familles Exploitation et Mesure du réalisé.
Équivalences de vocabulaire¶
Les termes ci-dessous sont ceux employés par les applications Pysae et par le secteur. Ils sont repris tels quels dans cette documentation.
| Français | Anglais |
|---|---|
| SAE (Système d'Aide à l'Exploitation) | CAD/AVL, AVM |
| SAEIV (SAE avec information voyageurs) | CAD/AVL with passenger information |
| SIV (Système d'Information Voyageurs) | PIS (Passenger Information System) |
| exploitant, opérateur | operator |
| conducteur | driver |
| course | trip |
| service de conduite | duty |
| régulation, supervision | supervision, dispatch |
| avance-retard | delay (early / late) |
| ponctualité | punctuality |
| déviation | detour, diversion |
| prise de service / fin de service | sign-on / sign-off |
| plan de transport | transport plan |
| fiche horaire | timetable |
| calculateur d'itinéraire | journey planner |
| arrêt | stop |
| ligne | route |
| réclamation voyageur | passenger complaint |
Conventions de lecture¶
- Les identifiants sont donnés sous la forme du paramètre de chemin qui les porte, par exemple
<driver_id>. - Les endpoints sont cités en
v4, la version par défaut. Le versionnement et les catégories sont décrits sur la page d'accueil. - Une entité dont les endpoints ne sont pas publiés dans le spec public est signalée comme telle : son concept est défini ici, mais elle ne s'appelle pas depuis une intégration externe.