Medición¶
Lo que se obtiene de la explotación una vez prestado el servicio: las distancias, la regularidad, la afluencia y el registro conservado de todo ello.
trip-km¶
Kilómetros recorridos — la distancia realizada, desglosada por expedición, por vehículo o por periodo. Sirve para la facturación por kilómetro, el seguimiento contractual y el dimensionamiento de la flota.
Sin identificador propio: el dato se obtiene por periodo y por ámbito.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/stats/trip-km |
Agrega los kilómetros de un periodo |
GET /api/v4/groups/<group_id>/export/trip-km |
Exporta el detalle en formato CSV |
Los kilómetros en vacío, recorridos fuera de expedición comercial, figuran en el servicio de conducción; consulte duties.
punctuality¶
Puntualidad — la medida de la diferencia entre el horario previsto y la hora de paso real, agregada sobre un periodo. Es el indicador de calidad del servicio que más siguen las autoridades de transporte.
Sin identificador propio: el dato se obtiene por periodo y por ámbito.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/stats/punctuality |
Agrega la puntualidad de un periodo |
GET /api/v4/groups/<group_id>/export/punctuality |
Exporta el detalle en formato CSV |
La medida se basa en los horarios teóricos (consulte stop-times) y en los pasos observados.
Un paso que un dispositivo telemático realizó antes de que su letrero mostrara la línea, reconstruido una vez mostrada la línea, no se cuenta ni en el agregado ni en la exportación. Permanece en el historial de pasos; el flujo de la expedición (trip-details-feed) lo indica con headsign_missing: true.
Perfiles de puntualidad — los umbrales que clasifican una diferencia en tres a cinco niveles: adelanto importante, adelanto, a la hora, retraso, retraso importante. Cada red define uno o varios (por ejemplo, urbano e interurbano), en minutos enteros con signo, y les asigna sus líneas; el perfil por defecto incluye todas las líneas que no incluye ningún otro perfil. Una diferencia es de adelanto si vale como máximo early × 60 segundos, de retraso si vale como mínimo late × 60, y a la hora entre ambos valores. early y late son obligatorios; big_early y big_late son opcionales, a null cuando el perfil no utiliza el nivel: si se indican, una diferencia de como máximo big_early × 60 es un adelanto importante y una diferencia de como mínimo big_late × 60, un retraso importante. Sin big_early, todo adelanto se queda en el nivel adelanto; sin big_late, todo retraso se queda en el nivel retraso. Una red nueva empieza con un perfil por defecto que no los indica.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/config/punctuality-profiles |
Proporciona los perfiles y su revisión |
PATCH /api/v4/groups/<group_id>/config/punctuality-profiles |
Sustituye la lista completa de perfiles, en la revisión leída |
Una vez guardados los perfiles, driver_ontime_interval ya no se modifica: vale [early × 60 + 1, late × 60] del perfil por defecto, para que las aplicaciones del conductor que ignoran los perfiles clasifiquen igual que las demás.
Colores de los niveles — el color de cada uno de los cinco niveles para toda la red, en #RRGGBB (guardado en mayúsculas). Un color null deja el nivel con su color por defecto, que elige la aplicación.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/config/punctuality-colors |
Proporciona los cinco colores, null para un color por defecto |
PATCH /api/v4/groups/<group_id>/config/punctuality-colors |
Sustituye los cinco colores |
passenger-counts¶
Recuento de viajeros — el número de subidas y bajadas registrado en las paradas, por expedición. Procede de los sistemas de recuento embarcados y sirve para dimensionar la oferta.
Sin identificador propio: el dato se obtiene por periodo y por ámbito.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/stats/passenger-counts |
Agrega la afluencia de un periodo |
GET /api/v4/groups/<group_id>/export/passenger-counts |
Exporta el detalle en formato CSV |
stats¶
Estadísticas — la familia transversal de los endpoints de agregación y exportación. No es una entidad en el sentido de las demás entradas: la etiqueta reúne los resultados calculados sobre las entidades anteriores, en dos formas constantes: un agregado bajo /stats/ y una exportación CSV bajo /export/.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/stats/vehicles-used |
Cuenta los vehículos empleados en un periodo |
GET /api/v4/groups/<group_id>/stats/daily-devices |
Cuenta los dispositivos activos por día |
GET /api/v4/groups/<group_id>/vehicle-amount |
Proporciona el número de vehículos del grupo |
Las ocho exportaciones CSV de la especificación datahub (expediciones, conductores, vehículos, alertas, puntualidad, kilómetros, seguimiento de expedición, recuento de viajeros) constituyen la vía recomendada para alimentar un almacén de datos. Se describen en los ejemplos de recogida.
history¶
Historial — la conservación de lo ocurrido, más allá de la ventana de tiempo real: eventos transmitidos por los dispositivos, horarios observados en las paradas, GTFS vigente en las fechas correspondientes, kilómetros registrados. Es la fuente que hay que consultar para reconstruir una jornada pasada.
Sin identificador propio: el historial se consulta por ámbito y por periodo.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/history/events |
Lista los eventos transmitidos por los dispositivos |
GET /api/v4/groups/<group_id>/history/stop-times |
Proporciona los pasos observados en las paradas (filtro opcional event: arrival o departure) |
GET /api/v4/groups/<group_id>/history/gtfs-active |
Proporciona el GTFS vigente en una fecha |
GET /api/v4/groups/<group_id>/devices/<device_id>/history |
Reconstruye la actividad de un dispositivo |
Los horarios observados que se conservan aquí no deben confundirse con los horarios previstos, que pertenecen a la referencia teórica; consulte stop-times.
Un cambio de expedición no constituye un paso por una parada. Los pasos de la nueva expedición se registran a partir de sus propios datos de parada; los de la expedición anterior se conservan.