Entity glossary¶
The API handles the business objects of a transit network: the schedule reference imported from GTFS, the resources committed to operate it, what actually happens in the field, and what is measured from it. This glossary defines each of those objects — its role, its identifier, its relations and the endpoints that expose it.
Each entry is named after the entity as it appears as a tag in the OpenAPI spec, so that the technical reference and this documentation refer to the same thing. The business term used by the teams, in French and in English, opens each entry.
The six families¶
| Family | What it covers |
|---|---|
| Organization | Who uses the API and within which perimeter: group, teams, users, roles, API keys |
| Network | The schedule reference: GTFS, trips, stop times, frequencies, planning |
| Fleet | The resources committed: drivers, vehicles, devices, depots, duties |
| Operations | What happens in service: trip events, updates, tracking, movements, danger zones |
| Communication | What is broadcast: alerts, messages, notifications, urgencies, telephony, GTFS-RT, SIRI |
| Measurement | What is derived from it: kilometres, punctuality, passenger counts, statistics, history |
The group, perimeter of every call¶
Almost every endpoint is prefixed with /groups/<group_id>. The group is the operated network: it holds its own data, and a given piece of data never exists outside a group. A call therefore always starts by knowing which group it applies to. See the groups entry.
Scheduled and actual¶
Two notions look alike and must not be confused:
- the scheduled side describes what is planned — it comes from the imported GTFS and only changes when a new GTFS is published;
- the actual side describes what happened — it originates from what the drivers' devices report during service.
A trip is scheduled; its execution on a given day is actual. Most entities in the Network family belong to the scheduled side, those in the Operations and Measurement families to the actual side.
Vocabulary equivalences¶
The terms below are those used by the Pysae applications and by the industry. They are reused as such throughout this documentation.
| French | English |
|---|---|
| SAE (Système d'Aide à l'Exploitation) | CAD/AVL, AVM |
| SAEIV (SAE with passenger information) | 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 |
Reading conventions¶
- Identifiers are given as the path parameter that carries them, for example
<driver_id>. - Endpoints are quoted in
v4, the default version. Versioning and categories are described on the home page. - An entity whose endpoints are not published in the public spec is flagged as such: its concept is defined here, but it is not called from an external integration.