Saltar a contenido

Expediciones

La expedición es el objeto central de la explotación. Es también el que menos sencillamente se designa: un identificador de expedición, por sí solo, nunca basta.

El triplete de identificación

Una expedición se designa mediante tres datos:

Elemento Por qué es necesario
El identificador de expedición Procede del GTFS y nombra el trayecto en el plan de transporte
La fecha de servicio La misma expedición circula cada día de explotación
El gtfs_id Un identificador de expedición solo es único dentro de su GTFS; por tanto, hay que saber de qué GTFS depende

Omitir la fecha equivale a pedir «la expedición 4218» sin decir qué día; omitir el gtfs_id equivale a pedir sus horarios sin decir según qué plan de transporte. Ambas omisiones producen resultados plausibles pero erróneos: es la trampa más costosa en la integración.

Los tres componentes forman una clave única: el triplete designa una y solo una ejecución de expedición, y nunca aparece duplicado.

Previsto y realizado

Una expedición contiene a la vez los dos tiempos del sistema.

Dónde se lee Qué proporciona
Previsto Los horarios del referencial, ver stop-times La hora a la que la expedición debía pasar por cada parada
Realizado Las transmisiones de los dispositivos, ver history La hora a la que pasó efectivamente

El adelanto-retraso no es un dato almacenado aparte: es la diferencia entre estas dos lecturas, parada por parada. La puntualidad es su agregado sobre un periodo.

Endpoint Función
GET /api/v4/groups/<group_id>/trips Lista las expediciones de un periodo
GET /api/v4/groups/<group_id>/trips/<trip_id> Describe una expedición
GET /api/v4/groups/<group_id>/stop-times Proporciona los horarios previstos en las paradas

Pasos observados por las paradas

Una llegada corresponde a la entrada en el estado detenido; las transmisiones posteriores durante la espera no crean una nueva llegada. Una salida corresponde a la salida de ese estado hacia la parada siguiente, aunque se hayan omitido paradas intermedias. Las oscilaciones GPS hacia la misma parada y los estados residuales de una expedición anterior no confirman una salida.

Si se observan varios pasos por la misma parada, se conserva aquel cuya diferencia absoluta con el horario teórico es menor. El historial de puntualidad, el seguimiento de expediciones v5 y el flujo GTFS-RT aplican esta misma regla. Esto puede corregir las estadísticas de puntualidad v5 y los horarios publicados en GTFS-RT, en particular cuando una deriva GPS había hecho aparecer una salida adelantada en la cabecera.

Las antiguas expediciones v5 siguen siendo legibles con su deducción histórica de las salidas. No se recalculan retroactivamente. La migración backfill_first_stop_departures puede corregir las salidas de la primera parada a partir de los pasos del historial, conservando el más cercano al teórico; no realiza una reproducción completa de las expediciones. La migración restore_backfill_stop_arrivals completa las llegadas a las paradas de las expediciones reconstruidas antes del cambio de cada grupo a partir de los pasos del historial del dispositivo, sin sustituir una llegada ya registrada, y después recalcula la parada atendida, la llegada a la cabecera y el retraso registrados.

Lo que el operador puede modificar

El referencial no se reescribe ante cada imprevisto. Una perturbación se traduce en una modificación de expedición que se superpone al teórico durante un periodo: parada suprimida, desplazada, añadida, expedición desviada o anulada. Ver trip-updates.

Un integrador no lee estas modificaciones directamente —no se publican en el spec público—, pero ve su efecto en los flujos de tiempo real descritos en la página siguiente y en las expediciones realizadas.

Las versiones v4 y v5

v4 es la versión por defecto de la API y la que utiliza esta guía.

v5 reescribe la lectura de las expediciones a partir de los eventos transmitidos por los dispositivos en lugar de un estado recalculado: la expedición realizada se reconstruye a partir de la secuencia de hechos observados. Este modo se activa grupo por grupo, y sus endpoints no se publican en el spec público a día de hoy; por tanto, una integración externa trabaja en v4.

Endpoint Función
GET /api/v5/groups/<group_id>/trips Lista las expediciones reconstruidas a partir de los eventos

Y después

Queda por entender de dónde proceden las transmisiones que alimentan lo realizado: ese es el objeto de la página Tiempo real.