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.