Saltar a contenido

Glosario de entidades

La API maneja los objetos de negocio de una red de transporte: la referencia teórica importada del GTFS, los medios empleados para explotarla, lo que ocurre realmente sobre el terreno y lo que se mide a partir de ello. Este glosario define cada uno de estos objetos: su función, su identificador, sus relaciones y los endpoints que lo exponen.

Cada entrada lleva el nombre de la entidad tal como aparece como tag en la especificación OpenAPI, para que la referencia técnica y esta documentación designen lo mismo. El término de negocio que emplean los equipos, en francés y en inglés, abre cada entrada.

Las seis familias

Familia Qué agrupa
Organización Quién utiliza la API y con qué alcance: grupo, equipos, usuarios, roles, claves de API
Red La referencia teórica: GTFS, expediciones, horarios en paradas, frecuencias, planificación
Flota Los medios empleados: conductores, vehículos, dispositivos, cocheras, servicios de conducción
Explotación Lo que ocurre en línea: eventos de expedición, modificaciones, seguimiento, movimientos, zonas peligrosas
Comunicación Lo que se difunde: alertas, mensajes, notificaciones, urgencias, telefonía, GTFS-RT, SIRI
Medición Lo que se obtiene: kilómetros, puntualidad, conteo de viajeros, estadísticas, históricos

El grupo, alcance de toda llamada

Casi todos los endpoints llevan el prefijo /groups/<group_id>. El grupo es la red explotada: contiene sus propios datos, y un mismo dato nunca existe fuera de un grupo. Por tanto, una llamada empieza siempre por saber a qué grupo se refiere. Consulte la entrada groups.

Teórico y realizado

Dos nociones se parecen y no deben confundirse:

  • lo teórico describe lo previsto: procede del GTFS importado y solo cambia al publicarse un nuevo GTFS;
  • lo realizado describe lo que ha ocurrido: nace de los datos que envían los dispositivos de los conductores durante el servicio.

Una expedición es teórica; su ejecución en un día concreto es realizada. La mayoría de las entidades de la familia Red pertenecen a lo teórico; las de las familias Explotación y Medición, a lo realizado.

Equivalencias de vocabulario

Los términos siguientes son los que emplean las aplicaciones de Pysae y el sector. Se utilizan tal cual en esta documentación.

Francés Inglés
SAE (Système d'Aide à l'Exploitation) CAD/AVL, AVM
SAEIV (SAE con información al viajero) 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

Convenciones de lectura

  • Los identificadores se indican con la forma del parámetro de ruta que los contiene, por ejemplo <driver_id>.
  • Los endpoints se citan en v4, la versión por defecto. El versionado y las categorías se describen en la página de inicio.
  • Una entidad cuyos endpoints no se publican en la especificación pública se indica como tal: su concepto se define aquí, pero no se invoca desde una integración externa.