Referencia de GTFS en tiempo real

Un feed GTFS en tiempo real permite que las empresas de transporte público brinden a los consumidores información en tiempo real acerca de las interrupciones de sus servicios (estaciones cerradas, líneas que no funcionan, demoras importantes, etc.), la ubicación de sus vehículos y tiempos de llegada esperados.

Las especificaciones de la versión 1.0 del feed se abordan y documentan en este sitio.

Definiciones de términos

  • obligatorio: uno
  • repetido: cero o más
  • mensaje: tipo complejo
  • enum.: lista de valores fijos

Índice de elementos

Elementos

mensaje FeedMessage

El contenido de un mensaje de feed. Cada mensaje en el flujo de datos se obtiene como una respuesta a una solicitud HTTP GET adecuada. Un feed en tiempo real siempre se define en relación con un feed GTFS existente. Todos los ID de entidades se resuelven en relación con el feed GTFS.

Un feed depende de algunas configuraciones externas:

  • El feed GTFS correspondiente.
  • La aplicación del feed (actualizaciones, posiciones o alertas). Un feed debe contener únicamente elementos de las aplicaciones correspondientes; todas las otras entidades se ignorarán.
  • Frecuencia de sondeo, controlada por min_update_delay, max_update_delay.

Campos

Nombre del campo Tipo Cardinalidad Descripción
header FeedHeader obligatorio Metadatos sobre este feed y mensaje del feed
entity FeedEntity repetido Contenido del feed

mensaje FeedHeader

Metadatos sobre un feed, incluido en los mensajes del feed

Campos

Nombre del campo Tipo Cardinalidad Descripción
gtfs_realtime_version string obligatorio Especificación de la versión del feed. La versión actual es 1.0.
incrementality Incrementality opcional
timestamp uint64 opcional Esta marca de tiempo identifica el momento en que se ha creado el contenido de este feed (en la hora del servidor). En la hora de POSIX (es decir, cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Para evitar el desvío de tiempos entre los sistemas que producen y que consumen información en tiempo real, se recomienda derivar la marca de tiempo desde un servidor de tiempo. Es absolutamente aceptable usar servidores de estrato 3 o, incluso, inferiores, porque las diferencias de tiempo de hasta un par de segundos son tolerables.

enum. Incrementality

Determina si la búsqueda actual es incremental.

  • FULL_DATASET: la actualización de este feed sobrescribirá toda la información en tiempo real anterior para el feed. Por lo tanto, se espera que esta actualización proporcione un resumen completo de toda la información en tiempo real conocida.
  • DIFFERENTIAL: en este momento, este modo no está admitido y su comportamiento no se especifica para los feeds que usan este modo. Existen debates sobre la lista de correo de GTFS en tiempo real, relacionados con la especificación completa del comportamiento del modo DIFFERENTIAL, y la documentación se actualizará cuando esos debates finalicen.

Valores

Valor
FULL_DATASET
DIFFERENTIAL

mensaje FeedEntity

La definición (o actualización) de una entidad en el feed de transporte público. Si la entidad no se elimina, uno de los campos "trip_update", "vehicle" y "alert" debe completarse.

Campos

Nombre del campo Tipo Cardinalidad Descripción
id string obligatorio Identificador único del feed para esta entidad. Los identificadores se usan solamente para proporcionar soporte de incrementalidad. Las entidades reales a las que hace referencia el feed deben especificarse mediante selectores explícitos (ver EntitySelector más adelante para obtener más información).
is_deleted bool opcional Establece si esta entidad debe eliminarse. Es relevante solo para las búsquedas incrementales.
trip_update TripUpdate opcional Datos sobre las demoras de salida en tiempo real de un viaje.
vehicle VehiclePosition opcional Datos sobre la posición en tiempo real de un vehículo.
alert Alert opcional Datos sobre las alertas en tiempo real.

mensaje TripUpdate

Actualización en tiempo real del progreso de un vehículo en un viaje. También consulta el debate general del tipo de feed de actualizaciones del viaje.

Según el valor de ScheduleRelationship, TripUpdate puede especificar lo siguiente:

  • Un viaje que avanza según la programación.
  • Un viaje que avanza por una ruta, pero que no tiene una programación fija.
  • Un viaje que se ha agregado o se ha quitado en relación con una programación.
Las actualizaciones pueden ser para eventos de llegada/salida futuros y previstos, o para eventos pasados que ya ocurrieron. En la mayoría de los casos, la información sobre los eventos pasados es un valor medido, por lo tanto, se recomienda que su valor de incertidumbre sea 0. Aunque puede haber algunos casos en que esto no sea así, por lo que se admiten valores de incertidumbre distintos de 0 para los eventos pasados. Si el valor de incertidumbre de una actualización no es 0, entonces la actualización es una predicción aproximada para un viaje que no se ha completado o la medición no es precisa o la actualización fue una predicción para el pasado que no se ha verificado después de que ocurrió el evento.

Ten en cuenta que la actualización puede describir un viaje que ya se ha completado. En este caso, es suficiente con proporcionar una actualización para la última parada del viaje. Si el tiempo de llegada para la última parada es en el pasado, el cliente concluirá que todo el viaje es pasado (es posible, aunque inconsecuente, proporcionar también actualizaciones para las paradas anteriores). Esta opción es más relevante para un viaje que se ha completado antes de lo que establecía la programación, pero que según esta, el viaje todavía se está realizando en este momento. Quitar las actualizaciones de este viaje podría hacer que el cliente considere que el viaje todavía se está realizando. Ten en cuenta que el proveedor del feed tiene permitido, aunque no está obligado, a purgar las actualizaciones pasadas (en este caso esto sería útil).

Campos

Nombre del campo Tipo Cardinalidad Descripción
trip TripDescriptor obligatorio El viaje al cual se aplica este mensaje. Puede haber una entidad de TripUpdate, como máximo, para cada instancia de viaje real. Si no hay ninguna, entonces no habrá información de predicciones disponible. *No* significa que el viaje se está realizando de acuerdo con la programación.
vehicle VehicleDescriptor opcional Información adicional sobre el vehículo con el cual se está realizando este viaje.
stop_time_update StopTimeUpdate repetido Las actualizaciones de StopTimes para el viaje (futuras, como las predicciones, y, en algunos casos, pasadas, es decir, aquellas que ya ocurrieron). Las actualizaciones deben ordenarse por secuencia de parada y deben aplicarse a todas las siguientes paradas del viaje hasta la próxima especificada.
timestamp uint64 opcional Momento en el que se midió el progreso en tiempo real del vehículo. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC).

mensaje StopTimeEvent

Información de horarios para un único evento previsto (sea la llegada o la salida). Los horarios consisten en la información sobre demoras o tiempos estimados y la incertidumbre.

  • La demora (delay) debe usarse cuando la predicción se realiza con relación a una programación existente en GTFS.
  • El tiempo (time) debe darse aunque no haya una programación prevista. Si se especifican tanto el tiempo como la demora, el tiempo será prioritario (aunque, por lo general, el tiempo, si se otorga para un viaje programado, debe ser igual al tiempo programado en GTFS + la demora).


La incertidumbre se aplica de la misma forma tanto al tiempo como a la demora. La incertidumbre especifica el error esperado en una demora real (pero ten en cuenta, que todavía no definimos su significado estadístico preciso). Es posible que la incertidumbre sea 0, por ejemplo, para los trenes que funcionan con un control de horarios por computadora.

Campos

Nombre del campo Tipo Cardinalidad Descripción
delay int32 opcional La demora (en segundos) puede ser positiva (significa que el vehículo está retrasado) o negativa (significa que el vehículo está adelantado). Una demora de 0 significa que el vehículo está yendo a tiempo.
time int64 opcional Evento como tiempo absoluto. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC).
uncertainty int32 opcional Si se omite la incertidumbre, se interpreta como desconocida. Para especificar una predicción completamente certera, establece la incertidumbre en 0.

mensaje StopTimeUpdate

La actualización en tiempo real para los eventos de llegada o de salida para una determinada parada de un viaje. Consulta el debate general de las actualizaciones de tiempos de parada en la documentación de TripDescriptor y del tipo de feed de actualizaciones de viaje.

Las actualizaciones se pueden proporcionar tanto para eventos pasados como futuros. El productor tiene permitido, aunque no está obligado, a desestimar los eventos pasados.
La actualización está vinculada a una parada específica sea a través de stop_sequence o de stop_id, de manera que uno de estos campos debe definirse, necesariamente.

Campos

Nombre del campo Tipo Cardinalidad Descripción
stop_sequence uint32 opcional Debe ser la misma que la de stop_times.txt en el feed GTFS correspondiente.
stop_id string opcional Debe ser el mismo que el de stops.txt en el feed GTFS correspondiente.
arrival StopTimeEvent opcional
departure StopTimeEvent opcional
schedule_relationship ScheduleRelationship opcional La relación predeterminada es SCHEDULED.

enum. ScheduleRelationship

La relación entre este StopTime y la programación estática

Valores

Valor Comentario
SCHEDULED El vehículo está avanzando según su programación estática de paradas, aunque no necesariamente de acuerdo con los tiempos de la programación. Este es el comportamiento predeterminado. Al menos debe proporcionarse uno de los valores de llegada y de salida. Si la programación para esta parada contiene los tiempos de llegada y de salida, entonces también debe contener estos dos valores la actualización. Una actualización son solo una salida, digamos, cuando la programación tiene ambos datos, indica que el viaje se termina antes en esta parada.
SKIPPED La parada se omite, es decir, el vehículo no se detendrá en esta parada. Los valores de llegada y salida son opcionales.
NO_DATA No se proporcionan datos para esta parada. Esto indica que no hay información en tiempo real disponible. Cuando se establece NO_DATA, esto se propaga en las siguientes paradas, de manera que esta es la forma recomendada de especificar desde qué parada no tienes información en tiempo real. Cuando se establece NO_DATA, no se deben proporcionar los datos de llegada ni de salida.

mensaje VehiclePosition

Información de posicionamiento en tiempo real para un vehículo dado

Campos

Nombre del campo Tipo Cardinalidad Descripción
trip TripDescriptor opcional El viaje que está haciendo este vehículo. Puede estar vacío o parcialmente vacío si el vehículo no puede identificarse con una instancia de viaje dada.
vehicle VehicleDescriptor opcional Información adicional sobre el vehículo que está realizando el viaje. Cada entrada debe tener un ID de vehículo único.
position Position opcional Posición actual de este vehículo.
current_stop_sequence uint32 opcional El índice de la secuencia de parada de la parada actual. El significado de current_stop_sequence (es decir, la parada a la que hace referencia) está determinado por current_status. Si falta el valor en current_status, se asume IN_TRANSIT_TO.
stop_id string opcional Identifica la parada actual. El valor debe ser el mismo que el de stops.txt en el feed GTFS correspondiente.
current_status VehicleStopStatus opcional El estado exacto del vehículo con respecto a la parada actual. Se ignora si falta el valor en current_stop_sequence.
timestamp uint64 opcional Momento en el cual se midió la posición del vehículo. En tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC).
congestion_level CongestionLevel opcional

enum. VehicleStopStatus

Valores

Valor Comentario
INCOMING_AT El vehículo está a punto de llegar a la parada (en la visualización de la parada, el símbolo del vehículo, por lo general, parpadea).
STOPPED_AT El vehículo está detenido en la parada.
IN_TRANSIT_TO El vehículo ha salido de la parada anterior y está en tránsito.

enum. CongestionLevel

El nivel de congestión que está afectando al vehículo.

Valores

Valor
UNKNOWN_CONGESTION_LEVEL
RUNNING_SMOOTHLY
STOP_AND_GO
CONGESTION
SEVERE_CONGESTION

mensaje Alert

Una alerta que indica que existe algún tipo de incidente en la red de transporte público.

Campos

Nombre del campo Tipo Cardinalidad Descripción
active_period TimeRange repetido Tiempo durante el cual debe mostrarse la alerta al usuario. Si falta, la alerta se mostrará durante todo el tiempo que aparezca en el feed. Si se otorgan varios intervalos, la alerta se mostrará durante todos ellos.
informed_entity EntitySelector repetido Entidades a cuyos usuarios debemos notificar esta alerta.
cause Cause opcional
effect Effect opcional
url TranslatedString opcional La URL que proporciona información adicional sobre la alerta.
header_text TranslatedString opcional Encabezado de la alerta. Esta cadena de texto sin formato se resaltará, por ejemplo, en negrita.
description_text TranslatedString opcional Descripción de la alerta. A esta cadena de texto sin formato se le aplicará el formato del cuerpo de la alerta (o se mostrará en una solicitud explícita de "expansión" realizada por el usuario
). La información de la descripción debe completar la información del encabezado.

enum. Cause

Causa de la alerta

Valores

Valor
UNKNOWN_CAUSE
OTHER_CAUSE
TECHNICAL_PROBLEM
STRIKE
DEMONSTRATION
ACCIDENT
HOLIDAY
WEATHER
MAINTENANCE
CONSTRUCTION
POLICE_ACTIVITY
MEDICAL_EMERGENCY

enum. Effect

El efecto de este problema en la entidad afectada.

Valores

Valor
NO_SERVICE
REDUCED_SERVICE
SIGNIFICANT_DELAYS
DETOUR
ADDITIONAL_SERVICE
MODIFIED_SERVICE
OTHER_EFFECT
UNKNOWN_EFFECT
STOP_MOVED

mensaje TimeRange

Un intervalo de tiempo. El intervalo se considera activo t si t es mayor o igual que la hora de inicio y mejor que la hora de finalización.

Campos

Nombre del campo Tipo Cardinalidad Descripción
start uint64 opcional Hora de inicio, en tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Si falta esta información, el intervalo comienza con el valor infinito negativo.
end uint64 opcional Hora de finalización, en tiempo de POSIX (es decir, la cantidad de segundos desde el 1.° de enero de 1970 00:00:00 UTC). Si falta esta información, el intervalo finaliza con el valor infinito positivo.

mensaje Position

La posición geográfica de un vehículo

Campos

Nombre del campo Tipo Cardinalidad Descripción
latitude float obligatorio Grados norte, en el sistema de coordenadas WGS-84
longitude float obligatorio Grados este, en el sistema de coordenadas WGS-84
bearing float opcional Orientación, en grados, en el sentido de las agujas del reloj desde el norte verdadero, es decir, 0 es el norte y 90 es el este. Esta puede ser la orientación de la brújula, o la dirección hacia la próxima parada o la ubicación intermedia. Esto no debe deducirse a partir de la secuencia de posiciones anteriores, que los clientes pueden calcular a partir de los datos anteriores.
odometer double opcional El valor del odómetro en metros.
speed float opcional Velocidad momentánea medida por el vehículo, en metros por segundo.

mensaje TripDescriptor

Un descriptor que identifica una instancia de un viaje de GTFS o todas las instancias de un viaje por una ruta. Para especificar una sola instancia de viaje, se define trip_id (y si fuera necesario, start_time). Si también se define route_id, debe ser el mismo que uno a los cuales corresponda el viaje dado. Para especificar todos los viajes de una determinada ruta, solo se debe definir route_id. Ten en cuenta que si no se conoce el trip_id, entonces los identificadores de la secuencia de la estación en TripUpdate no son suficientes y, también, se deberán proporcionar los identificadores de parada. Además, se deben proporcionar las horas absolutas de llegada/salida.

Campos

Nombre del campo Tipo Cardinalidad Descripción
trip_id string opcional El identificador de viaje del feed GTFS al cual hace referencia este selector. Para los viajes sin frecuencia extendida, este campo es suficiente para identificar de forma unívoca al viaje. Para los viajes con frecuencia extendida, también podrían necesitarse start_time y start_date.
route_id string opcional El identificador de la ruta de GTFS al que hace referencia este selector.
start_time string opcional La hora de inicio programada de esta instancia de viaje. Este campo debe proporcionarse solo si el viaje tiene frecuencia extendida en el feed GTFS. El valor debe corresponder precisamente a la hora de inicio especificada para la ruta del feed GTFS más algunos múltiplos de headway_secs. El formato del campo es el mismo que el de GTFS/frequencies.txt/start_time, es decir, 11:15:35 o 25:15:35.
start_date string opcional La fecha de inicio programada de esta instancia de viaje. Este campo debe proporcionarse para desambiguar los viajes que están tan retrasados que pueden superponerse con un viaje programado para el día siguiente. Por ejemplo, para un tren que sale a las 8:00 y a las 20:00 todos los días, y está 12 horas retrasado, habrá dos viajes distintos a la misma hora. Este campo puede proporcionarse, pero no es obligatorio para las programaciones en las cuales las superposiciones son imposibles, por ejemplo, un servicio que funciona según una programación horaria donde un vehículo que está una hora retrasado deja de considerarse relacionado a la programación. En formato AAAAMMDD.
schedule_relationship ScheduleRelationship opcional

enum. ScheduleRelationship

La relación entre este viaje y la programación estática. Si un viaje se realiza de acuerdo con la programación temporal, no se refleja en GTFS, y por lo tanto, no debe marcarse como SCHEDULED, sino como ADDED.

Valores

Valor Comentario
SCHEDULED Viaje que se está realizando de acuerdo con su programación de GTFS, o que está realizándose tan parecido al viaje programado que se puede asociar con él.
ADDED Un viaje adicional que se agregó además de una programación existente, por ejemplo, para reemplazar un vehículo averiado o para responder a una carga repentina de pasajeros.
UNSCHEDULED Un viaje que se está realizando sin ninguna programación asociada, por ejemplo, cuando no existe ninguna programación.
CANCELED Un viaje que existió en la programación, pero que luego se eliminó.
REPLACEMENT Un viaje que reemplaza una parte de la programación estática. Si el selector de viaje identifica determinada instancia de viaje, entonces solamente esa instancia se reemplaza. Si el selector identifica una ruta, entonces todos los viajes de la ruta se reemplazan.

El reemplazo se aplica solamente a la parte del viaje que se suministra. Por ejemplo, consideremos una ruta que pasa por las paradas A,B,C,D,E,F y un viaje REPLACEMENT proporciona datos para las paradas A,B,C. Entonces, los horarios para las paradas D,E,F todavía se toman de la programación estática.

Un feed debe suministrar varios viajes REPLACEMENT. En este caso, la parte de la programación estática que se reemplaza es la suma de las definiciones de todos los feeds. Por lo general, todos los viajes REPLACEMENT deben corresponder a la misma ruta o a instancias de viaje individuales.

mensaje VehicleDescriptor

Información de identificación para el vehículo que realiza el viaje.

Campos

Nombre del campo Tipo Cardinalidad Descripción
id string opcional Identificación interna del sistema para el vehículo. Debe ser única para cada vehículo y se usa para hacer un seguimiento del vehículo en la medida en que avanza en el sistema. Este identificador debe ser visible para el usuario final; para ello debes usar el campo label
label string opcional Etiqueta visible para el usuario, es decir, que se debe mostrar al pasajero para ayudarlo a identificar el vehículo correcto.
license_plate string opcional La patente del vehículo.

mensaje EntitySelector

Un selector para una entidad en un feed GTFS. Los valores de los campos deben coincidir con los campos correspondientes del feed GTFS. Debe otorgarse al menos un especificador. Si se otorgan muchos, entonces la coincidencia debe hacerse con todos los especificadores dados.

Campos

Nombre del campo Tipo Cardinalidad Descripción
agency_id string opcional
route_id string opcional
route_type int32 opcional
trip TripDescriptor opcional
stop_id string opcional

mensaje TranslatedString

Un mensaje internacionalizado que contiene versiones por idioma de un fragmento de texto o una URL. Se seleccionará una de las cadenas de un mensaje. La resolución se realiza de la siguiente manera: si el idioma de la IU coincide con el código de idioma de una traducción, se elije la primera traducción coincidente. Si un idioma de IU predetermiando (por ejemplo, inglés) coincide con el código de idioma de una traducción, se elije la primera traducción coincidente. Si alguna traducción tiene un código de idioma no especificado, se elija esa traducción.

Campos

Nombre del campo Tipo Cardinalidad Descripción
translation Translation repetido Se debe proporcionar al menos una traducción.

mensaje Translation

Una cadena localizada asignada a un idioma.

Campos

Nombre del campo Tipo Cardinalidad Descripción
text string obligatorio Una cadena UTF-8 que contiene el mensaje.
language string opcional Código de idioma BCP-47. Se puede omitir si el idioma es desconocido o si no se realiza ninguna internacionalización para el feed. Al menos una traducción puede tener una etiqueta de idioma no especificado.