Un feed GTFS Realtime permite que las empresas de transporte público brinden a los usuarios información en tiempo real sobre las interrupciones en sus servicios (estaciones cerradas, líneas que no funcionan, retrasos importantes, etc.), la ubicación de sus vehículos y los horarios de llegada esperados.
La versión 2.0 de la especificación del feed se analiza y documenta en este sitio.
Definiciones de términos
Obligatorio
En la v2.0 o versiones superiores de la especificación GTFS-realtime, en la columna Obligatorio, se describe qué campos debe proporcionar un productor a fin de que los datos de transporte público sean válidos y tengan sentido para una aplicación de consumo.
Los siguientes valores se utilizan en el campo Obligatorio:
- Obligatorio: El productor del feed GTFS-realtime debe proveer un valor para este campo.
- Condicionalmente obligatorio: Este campo es obligatorio en determinadas condiciones, las cuales se explican en el campo Descripción. Fuera de estas condiciones, el campo es opcional.
- Opcional: Este campo es opcional y el productor no tiene la obligación de implementarlo. Sin embargo, si los datos están disponibles en los sistemas subyacentes de ubicación automática del vehículo (p. ej.,
VehiclePositiontimestamp), se recomienda que los productores proporcionen estos campos opcionales cuando sea posible.
Ten en cuenta que, en la versión 1.0 de la especificación GTFS en tiempo real, no se definieron los requisitos semánticos y, por lo tanto, es posible que los feeds con gtfs_realtime_version igual a 1 no cumplan con estos requisitos. Para obtener información más detallada, consulta la propuesta de requisitos semánticos.
Cardinalidad
La cardinalidad representa la cantidad de elementos que se pueden proporcionar en un campo en particular. Estos elementos pueden tener los siguientes valores:
- Uno: Se puede proporcionar un solo elemento para este campo. Esto se mapea con las cardinalidades obligatorio y opcional del búfer de protocolo.
- Muchos: Se pueden proporcionar muchos elementos (0, 1 o más) para este campo. Esto se mapea con la cardinalidad repetido del búfer de protocolo.
Para saber cuándo un campo es obligatorio, opcional o condicionalmente obligatorio, consulta siempre los campos Obligatorio y Descripción. Para conocer la cardinalidad del búfer de protocolo, consulta gtfs-realtime.proto.
Tipos de datos del búfer de protocolo
Los siguientes tipos de datos del búfer de protocolo se utilizan para describir los elementos del feed:
- message: tipo complejo
- enum.: lista de valores fijos
Campos experimentales
Los campos etiquetados como experimentales están sujetos a cambio y aún no se han adoptado formalmente en la especificación. Es posible que un campo experimental se adopte formalmente en el futuro.
Índice de elementos
Elementos
mensaje FeedMessage
Es el contenido de un mensaje de feed. Cada mensaje de la transmisión se obtiene como 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 entidad se resuelven con respecto al feed GTFS.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
header |
FeedHeader |
Obligatorio | Uno | Metadatos sobre este feed y sobre el mensaje del feed |
entity |
FeedEntity |
Condicionalmente obligatorio | Muchos | Contenidos del feed. Si hay información en tiempo real disponible para el sistema de transporte público, se debe proporcionar un valor para este campo. Si este campo está vacío, los usuarios deben suponer que no hay información en tiempo real disponible para el sistema. |
mensaje FeedHeader
Metadatos sobre un feed, incluido en los mensajes del feed.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
gtfs_realtime_version |
string |
Obligatorio | Uno | Versión de la especificación del feed. La versión actual es 2.0. |
incrementality |
Incrementality |
Obligatorio | Uno | |
timestamp |
uint64 |
Obligatorio | Uno | Esta marca de tiempo identifica el momento en el que se creó el contenido de este feed (en la hora del servidor), expresado en tiempo POSIX (es decir, la cantidad de segundos desde el 1 de enero de 1970 a las 00:00:00, UTC). Para evitar el desvío de tiempo entre los sistemas que producen y que consumen información en tiempo real, se recomienda derivar timestamp desde un servidor de tiempo. Es totalmente aceptable utilizar servidores de estrato 3 o, incluso, inferiores, ya que 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 reemplazará 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 se admite, y el comportamiento no se especifica para los feeds que usan este modo. En la lista de distribución de GTFS Realtime, hay debates relacionados con la especificación completa del comportamiento del modoDIFFERENTIAL. La documentación correspondiente se actualizará cuando esos debates finalicen.
Valores
| Valor |
|---|
FULL_DATASET |
DIFFERENTIAL |
mensaje FeedEntity
Es la definición (o actualización) de una entidad en el feed de transporte público. Si la entidad no se borra, se debe propagar uno de los campos trip_update, vehicle o alert.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
id |
string |
Obligatorio | Uno | Identificador único del feed para esta entidad. Los ID solo se utilizan para proporcionar soporte de incrementalidad. Las entidades reales a las que hace referencia el feed se deben especificar mediante selectores explícitos (para obtener más información, consulta EntitySelector más adelante). |
is_deleted |
bool |
Opcional | Uno | Establece si esta entidad se debe borrar. Debe proporcionarse solo para los feeds con una Incrementality de DIFFERENTIAL. Este campo NO debe proporcionarse para los feeds con una Incrementality de FULL_DATASET. |
trip_update |
TripUpdate |
Condicionalmente obligatorio | Uno | Son datos sobre los retrasos de salida en tiempo real de un viaje. Se debe proporcionar al menos uno de los campos trip_update, vehicle o alert. Estos campos no pueden estar todos vacíos. |
vehicle |
VehiclePosition |
Condicionalmente obligatorio | Uno | Son datos sobre la posición en tiempo real de un vehículo. Se debe proporcionar al menos uno de los campos trip_update, vehicle o alert. Estos campos no pueden estar todos vacíos. |
alert |
Alert |
Condicionalmente obligatorio | Uno | Son datos sobre las alertas en tiempo real. Se debe proporcionar al menos uno de los campos trip_update, vehicle o alert. Estos campos no pueden estar todos vacíos. |
mensaje TripUpdate
Actualización en tiempo real del progreso de un vehículo en un viaje. Consulta también el debate general de las entidades de actualizaciones de viajes.
Según el valor de ScheduleRelationship, un mensaje TripUpdate puede especificar lo siguiente:
- Un viaje que avanza según el horario programado
- Un viaje que avanza por una ruta, pero que no tiene un horario programado
- Un viaje que se agregó o quitó, en relación con un horario programado
Las actualizaciones pueden ser para eventos de llegada y 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. No obstante, puede haber algunos casos en los 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, significa que la actualización es una predicción aproximada para un viaje que no se completó, la medición no es precisa o la actualización fue una predicción para un evento pasado que no se verificó después de que ocurrió dicho evento.
Ten en cuenta que la actualización puede describir un viaje que ya se completó. En este caso, basta con proporcionar una actualización para la última parada del viaje. Si el tiempo de llegada a la última parada es en el pasado, el cliente concluirá que todo el viaje es pasado (es posible proporcionar también actualizaciones para las paradas anteriores, aunque no tiene mucho sentido hacerlo). Esta opción es la más relevante para un viaje que se completó antes de lo establecido en el horario, pero que, según este, todavía está en curso en este momento. Quitar las actualizaciones de este viaje podría hacer que el cliente considere que el viaje todavía está en curso. Ten en cuenta que el proveedor del feed tiene permitido borrar definitivamente las actualizaciones pasadas, aunque no está obligado a hacerlo. Sin embargo, si decide hacerlo en este caso, sería de utilidad.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
trip |
TripDescriptor |
Obligatorio | Uno | Indica el viaje al cual se aplica este mensaje. Puede haber, como máximo, una entidad TripUpdate para cada instancia de viaje real. Si no hay ninguna, no habrá información sobre predicciones disponible. Esto no significa que el viaje está en curso de acuerdo con el horario programado. |
vehicle |
VehicleDescriptor |
Opcional | Uno | Proporciona información adicional sobre el vehículo que está realizando el viaje. |
stop_time_update |
StopTimeUpdate |
Condicionalmente obligatorio | Muchos | Son las actualizaciones de StopTimes para el viaje (futuras, como las predicciones, y, en algunos casos, pasadas, las que ya ocurrieron). Las actualizaciones deben ordenarse por stop_sequence y aplicarse a todas las siguientes paradas del viaje hasta la próxima stop_time_update especificada. Se debe proporcionar al menos una stop_time_update para el viaje, a menos que trip.schedule_relationship tenga un valor de CANCELED. Si se cancela el viaje, no es necesario proporcionar stop_time_updates. |
timestamp |
uint64 |
Opcional | Uno | Momento en el que se midió el progreso en tiempo real del vehículo, expresado en tiempo POSIX (es decir, la cantidad de segundos desde el 1 de enero de 1970 a las 00:00:00, UTC). |
delay |
int32 |
Opcional | Uno | Indica la desviación actual del horario del viaje. El delay solo se debe especificar cuando la predicción se realiza con relación a un horario existente en GTFS.El delay (en segundos) puede ser positivo (significa que el vehículo está retrasado) o negativo (significa que el vehículo está adelantado). Un delay de 0 significa que el vehículo está exactamente a horario.La información de retraso en StopTimeUpdates tiene prioridad sobre la información de retraso a nivel del viaje. Tal es así que en los viajes con un valor de StopTimeUpdate delay especificado, el retraso a nivel del viaje solo se propaga hasta la siguiente parada.Se recomienda que los proveedores de feeds proporcionen un valor de TripUpdate.timestamp que indique cuándo se actualizó por última vez el valor del delay a fin de evaluar la vigencia de los datos.Precaución: Este campo aún es experimental y está sujeto a cambios. Es posible que se adopte de manera formal en un futuro. |
mensaje StopTimeEvent
Información de horarios para un solo evento previsto (ya sea la llegada o la partida). Los horarios incluyen información sobre incertidumbre, retrasos y tiempos estimados.
- El campo
delayse debe utilizar cuando la predicción se realiza con relación a un horario existente en la especificación GTFS. - La información de
timese debe brindar siempre, aunque no haya un horario previsto. Si se especifican los valores detimeydelay,timetendrá prioridad (aunque, por lo general, si se especificatimeen un viaje programado, este valor debe ser igual al tiempo programado en GTFS más el retraso).
La incertidumbre se aplica de la misma forma tanto para el tiempo como para el retraso. La incertidumbre especifica, aproximadamente, el error esperado en un retraso 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 | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
delay |
int32 |
Condicionalmente obligatorio | Uno | El campo delay (en segundos) puede ser positivo (significa que el vehículo está retrasado) o negativo (significa que el vehículo está adelantado). Un delay de 0 significa que el vehículo está en horario. Se debe especificar al menos uno de los valores delay o time en StopTimeEvent. Estos campos no pueden estar los dos vacíos. |
time |
int64 |
Condicionalmente obligatorio | Uno | Evento como tiempo absoluto, expresado en tiempo POSIX (es decir, la cantidad de segundos desde el 1 de enero de 1970 a las 00:00:00, UTC). Se debe especificar al menos uno de los valores delay o time en StopTimeEvent. Estos campos no pueden estar los dos vacíos. |
uncertainty |
int32 |
Opcional | Uno | 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 también el debate general de las actualizaciones de horarios de paradas en los documentos de TripDescriptor y de entidades de actualizaciones de viajes.
Las actualizaciones se pueden proporcionar tanto para eventos pasados como futuros. El productor tiene permitido brindar información sobre eventos pasados, aunque no está obligado a hacerlo.
La actualización está vinculada a una parada específica, ya sea a través de stop_sequence o stop_id, por lo que se debe establecer al menos uno de estos campos. Si en un viaje se usa el mismo stop_id más de una vez, se debe proporcionar el valor de stop_sequence en todos los mensajes StopTimeUpdates correspondientes a ese stop_id en ese viaje.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
stop_sequence |
uint32 |
Condicionalmente obligatorio | Uno | Debe ser la misma que en stop_times.txt en el feed GTFS correspondiente. Se debe especificar, al menos, uno de los valores stop_sequence o stop_id en StopTimeUpdate. Estos campos no pueden estar los dos vacíos. Se requiere un valor stop_sequence en los viajes que usan el mismo stop_id más de una vez (p. ej., un bucle) a fin de identificar la parada a la cual corresponde la predicción. |
stop_id |
string |
Condicionalmente obligatorio | Uno | Debe ser la misma que en stops.txt en el feed GTFS correspondiente. Se debe especificar, al menos, uno de los valores stop_sequence o stop_id en StopTimeUpdate. Estos campos no pueden estar los dos vacíos. |
arrival |
StopTimeEvent |
Condicionalmente obligatorio | Uno | Si el campo schedule_relationship está vacío o SCHEDULED, se debe proporcionar arrival o departure en StopTimeUpdate. Estos campos no pueden estar los dos vacíos. Ambos campos arrival y departure pueden estar vacíos cuando schedule_relationship tiene el valor SKIPPED. Si schedule_relationship tiene el valor NO_DATA, arrival y departure deben estar vacíos. |
departure |
StopTimeEvent |
Condicionalmente obligatorio | Uno | Si el campo schedule_relationship está vacío o SCHEDULED, se debe proporcionar arrival o departure en StopTimeUpdate. Estos campos no pueden estar los dos vacíos. Ambos campos arrival y departure pueden estar vacíos cuando schedule_relationship tiene el valor SKIPPED. Si schedule_relationship tiene el valor NO_DATA, arrival y departure deben estar vacíos. |
schedule_relationship |
ScheduleRelationship |
Opcional | Uno | La relación predeterminada es SCHEDULED. |
enum ScheduleRelationship
Es la relación entre este StopTime y el horario estático.
Valores
| Valor | Comentario |
|---|---|
SCHEDULED |
El vehículo avanza según el horario estático de las paradas, aunque no necesariamente de acuerdo con los tiempos del horario. Este es el comportamiento predeterminado. Se debe proporcionar, al menos, uno de los valores arrival o departure. |
SKIPPED |
La parada se omite, es decir, el vehículo no se detendrá en esta parada. Los campos arrival y departure 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 a 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 arrival ni departure. |
mensaje VehiclePosition
Información de posicionamiento en tiempo real para un vehículo dado
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
trip |
TripDescriptor |
Opcional | Uno | El viaje que está haciendo este vehículo. Puede estar vacío o parcialmente vacío si el vehículo no se puede identificar con una instancia de viaje específica. |
vehicle |
VehicleDescriptor |
Opcional | Uno | Proporciona 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 | Uno | Indica la posición actual de este vehículo. |
current_stop_sequence |
uint32 |
Opcional | Uno | Es el índice de la secuencia de paradas 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 de current_status, se supone que es IN_TRANSIT_TO. |
stop_id |
string |
Opcional | Uno | Identifica la parada actual. El valor debe ser el mismo que el de stops.txt en el feed GTFS correspondiente. |
current_status |
VehicleStopStatus |
Opcional | Uno | Indica el estado exacto del vehículo con respecto a la parada actual. Se ignora si falta current_stop_sequence. |
timestamp |
uint64 |
Opcional | Uno | Momento en el cual se midió la posición del vehículo, expresado en tiempo POSIX (es decir, la cantidad de segundos desde el 1 de enero de 1970 a las 00:00:00, UTC). |
congestion_level |
CongestionLevel |
Opcional | Uno | |
occupancy_status |
OccupancyStatus |
Opcional | Uno | El nivel de ocupación de pasajeros del vehículo. Precaución: Este campo aún es experimental y está sujeto a cambios. Es posible que se adopte de manera formal en un futuro. |
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 salió 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 |
enum OccupancyStatus
El nivel de ocupación de pasajeros del vehículo.
Precaución: Este campo aún es experimental y está sujeto a cambios. Es posible que se adopte de manera formal en un futuro.
Valores
| Valor | Comentario |
|---|---|
EMPTY |
En la mayoría de las medidas, se considera que el vehículo está vacío y tiene pocos o ningún pasajero a bordo, pero aún acepta pasajeros. |
MANY_SEATS_AVAILABLE |
El vehículo o vagón tiene un gran porcentaje de asientos disponibles. El productor determina, a su discreción, cuál es el porcentaje de asientos libres del total de asientos disponibles que se considera espacio lo suficientemente grande como para incluirse en esta categoría. |
FEW_SEATS_AVAILABLE |
El vehículo o vagón tiene un pequeño porcentaje de asientos disponibles. El productor determina, a su discreción, cuál es el porcentaje de asientos libres del total de asientos disponibles que se considera espacio lo suficientemente pequeño como para incluirse en esta categoría. |
STANDING_ROOM_ONLY |
Actualmente, el vehículo o vagón solo puede aceptar pasajeros de pie. |
CRUSHED_STANDING_ROOM_ONLY |
Actualmente, el vehículo o vagón solo puede aceptar pasajeros de pie y tiene espacio limitado para ellos. |
FULL |
En la mayoría de las medidas, se considera que el vehículo está lleno, pero es posible que aún acepte pasajeros a bordo. |
NOT_ACCEPTING_PASSENGERS |
El vehículo o vagón no acepta pasajeros. Por lo general, el vehículo o vagón acepta pasajeros para abordar. |
NO_DATA_AVAILABLE |
El vehículo o vagón no tiene datos de ocupación disponibles en ese momento. |
NOT_BOARDABLE |
No es posible subirse al vehículo o vagón y nunca acepta pasajeros. Esta opción resulta útil para vehículos o vagones especiales (motor, vagón de mantenimiento, etcétera). |
Alerta de mensaje
Una alerta que indica que existe algún tipo de incidente en la red de transporte público.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
active_period |
TimeRange |
Opcional | Muchos | Tiempo durante el cual se debe mostrar la alerta al usuario. Si falta, la alerta se mostrará durante todo el tiempo que aparezca en el feed. Si se establecen varios intervalos, la alerta se mostrará durante todos ellos. |
informed_entity |
EntitySelector |
Obligatorio | Muchos | Entidades a cuyos usuarios debemos notificar esta alerta. Se debe proporcionar, al menos, un valor de informed_entity. |
cause |
Cause |
Opcional | Uno | |
effect |
Effect |
Opcional | Uno | |
url |
TranslatedString |
Opcional | Uno | Es la URL que proporciona información adicional sobre la alerta. |
header_text |
TranslatedString |
Obligatorio | Uno | Encabezado de la alerta. Esta string de texto sin formato se destacará, por ejemplo, en negrita. |
description_text |
TranslatedString |
Obligatorio | Uno | 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 en el momento t si t es superior o igual a la hora de start e inferior a la hora de end.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
start |
uint64 |
Condicionalmente obligatorio | Uno | Hora de inicio, expresada en tiempo POSIX (es decir, la cantidad de segundos desde el 1 de enero de 1970 a las 00:00:00, UTC). Si falta esta información, el intervalo comienza con un valor infinito negativo. Si se proporciona un TimeRange, se debe brindar un valor para start o end. Estos campos no pueden estar los dos vacíos. |
end |
uint64 |
Condicionalmente obligatorio | Uno | Hora de finalización, expresada en tiempo POSIX (es decir, la cantidad de segundos desde el 1 de enero de 1970 a las 00:00:00, UTC). Si falta esta información, el intervalo finaliza con un valor infinito positivo. Si se proporciona un TimeRange, se debe brindar un valor para start o end. Estos campos no pueden estar los dos vacíos. |
mensaje Position
La posición geográfica de un vehículo
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
latitude |
float |
Obligatorio | Uno | Grados norte, en el sistema de coordenadas WGS84 |
longitude |
float |
Obligatorio | Uno | Grados este, en el sistema de coordenadas WGS84 |
bearing |
float |
Opcional | Uno | Orientación, en grados, en sentido horario desde el norte verdadero; es decir, 0 es el norte y 90 es el este. Esto puede ser la orientación de la brújula o la dirección hacia la siguiente 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 | Uno | El valor del odómetro en metros |
speed |
float |
Opcional | Uno | Velocidad momentánea medida por el vehículo, en metros por segundo. |
mensaje TripDescriptor
Un descriptor que identifica una única instancia de un viaje de GTFS.
Para especificar una sola instancia de viaje, un trip_id funciona bien en muchos casos.
Sin embargo, los siguientes casos requieren información adicional para resolver una sola instancia de viaje:
- Si el viaje se define en el archivo
frequencies.txt, se deben incluir valores destart_dateystart_time, además detrip_id. - Si el viaje dura más de 24 horas o se retrasa de manera tal que se superpondría con un viaje programado para el día siguiente, debes proporcionar los dos valores de
start_dateytrip_id. - Si no se puede proporcionar el campo
trip_id, debes incluir los camposroute_id,direction_id,start_dateystart_time.
En todos los casos, si se proporcionan route_id y trip_id, route_id debe coincidir con el campo route_id asignado al viaje dado en el archivo trips.txt de GTFS.
El campo trip_id no puede, por sí mismo o en combinación con otros campos TripDescriptor, usarse para identificar varias instancias de viaje. Si TripDescriptor no resuelve ninguna instancia de viaje, o bien resuelve varias, en lugar de una sola, esto se considera un error. Es posible que los usuarios descarten la entidad que contiene el campo TripDescriptor erróneo.
Por ejemplo, si se define un viaje en el archivo frequencies.txt de GTFS con un valor de exact_times=0, un TripDescriptor nunca debe especificar trip_id por sí mismo. Esto se debe a que, cuando resuelves una sola instancia de viaje que comienza en un horario específico del día, también debes proporcionar un valor de start_time.
Ten en cuenta que, si no se conoce el trip_id, los ID de la secuencia de estación de TripUpdate no son suficientes, y también se deberán proporcionar los campos stop_id. Además, se deben incluir las horas absolutas de llegada y salida.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
trip_id |
string |
Condicionalmente obligatorio | Uno | El trip_id del feed GTFS al cual hace referencia este selector. El campo trip_id es obligatorio según el tipo de viaje: • Viajes que no están basados en la frecuencia: El campo trip_id por sí solo es suficiente para identificar estos viajes de forma exclusiva. Ten en cuenta que estos viajes no se definen en el archivo frequencies.txt de GTFS. • Viajes basados en la frecuencia: Los campos trip_id, start_time y start_date son obligatorios. Los viajes basados en la frecuencia se definen en el archivo frequencies.txt de GTFS. • Viajes basados en horarios: El campo trip_id solo se puede omitir en caso de que el viaje se pueda identificar de forma exclusiva mediante una combinación de los campos route_id, direction_id, start_time y start_date. Ten en cuenta que estos viajes no se definen en el archivo frequencies.txt de GTFS. |
route_id |
string |
Condicionalmente obligatorio | Uno | El route_id del feed GTFS al cual hace referencia este selector. Si se omite trip_id, se deben configurar route_id, direction_id, start_time y schedule_relationship=SCHEDULED para identificar una instancia de viaje. |
direction_id |
uint32 |
Condicionalmente obligatorio | Uno | Es el direction_id del archivo trips.txt del feed GTFS, que indica la dirección del viaje. Si se omite trip_id, se debe proporcionar direction_id. Precaución: Este campo aún es experimental y está sujeto a cambios. Es posible que se adopte de manera formal en el futuro. |
start_time |
string |
Condicionalmente obligatorio | Uno | La hora de inicio programada inicialmente de esta instancia de viaje. El tipo de campo Time define el formato de este campo, por ejemplo, 11:15:35 o 25:15:35. El campo start_time es obligatorio según el tipo de viaje: • El trip_id corresponde a un viaje que no está basado en la frecuencia: El campo start_time se debe omitir, o bien su valor debe ser igual al de departure_time en el archivo stop_times.txt del feed GTFS. • El trip_id corresponde a un viaje basado en la frecuencia: start_time siempre es obligatorio y se debe especificar para las actualizaciones de viajes y las posiciones de vehículos. Los viajes basados en la frecuencia se definen en el archivo frequencies.txt de GTFS. ◦ Si el viaje basado en la frecuencia corresponde a un registro exact_times=1 de GTFS: El campo start_time debe ser un múltiplo (incluido el cero) de headway_secs superior al valor start_time del archivo frequencies.txt para el período correspondiente. ◦ Si el viaje basado en la frecuencia corresponde a un registro exact_times=0 de GTFS: El start_time puede ser arbitrario, y se espera que inicialmente sea la primera salida del viaje. Una vez establecido, el start_time de este viaje basado en la frecuencia con un valor de exact_times=0 se considera inmutable, incluso si el primer horario de salida se modifica. Cualquier cambio de horario posterior se puede reflejar en un mensaje StopTimeUpdate. • Se omite trip_id: Se debe proporcionar start_time. |
start_date |
string |
Condicionalmente obligatorio | Uno | Es la fecha de inicio de esta instancia de viaje en formato YYYYMMDD. El campo start_date es obligatorio según el tipo de viaje: • Viajes programados: Se debe proporcionar start_date a fin de desambiguar los viajes que están tan retrasados que se superponen 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ía dos viajes distintos programados para la misma hora. Nota: Este campo es opcional para los viajes programados en los que es imposible que se produzca tal superposición. Por ejemplo, esto podría suceder si un servicio funciona cada hora y un vehículo que está una hora retrasado se deja de considerar como relacionado al horario. • Viajes basados en la frecuencia: Se debe proporcionar start_date. Ten en cuenta que estos viajes se definen en el archivo frequencies.txt de GTFS, mientras que los viajes programados no. • Se omite trip_id: Se debe proporcionar start_date. |
schedule_relationship |
ScheduleRelationship |
Opcional | Uno | La relación entre este viaje y el horario estático. Si se proporciona TripDescriptor en un EntitySelector de Alert, los usuarios ignoran el campo schedule_relationship cuando identifican la instancia de viaje coincidente. |
enum ScheduleRelationship
La relación entre este viaje y el horario estático. Si un viaje se realiza de acuerdo con el horario temporal, no se refleja en GTFS y, por lo tanto, no se debe marcar como SCHEDULED, sino como ADDED.
Valores
| Valor | Comentario |
|---|---|
SCHEDULED |
Viaje que se está realizando de acuerdo con su horario de GTFS o que es lo suficientemente parecido al viaje programado como para poder asociarlo con él. |
ADDED |
Un viaje adicional que se agregó además de un horario existente; por ejemplo, para reemplazar un vehículo averiado o para responder a un aumento repentino en la demanda de pasajeros. |
UNSCHEDULED |
Un viaje que se está realizando sin ningún horario asociado. Este valor se utiliza para identificar los viajes definidos en el archivo frequencies.txt de GTFS con un valor de exact_times = 0. No se debe usar para describir viajes que no están definidos en el archivo frequencies.txt de GTFS ni para los viajes que tenga un valor de exact_times = 1 en el archivo frequencies.txt de GTFS. |
CANCELED |
Un viaje que existió en el horario, pero que, luego, se quitó. |
mensaje VehicleDescriptor
Información de identificación para el vehículo que realiza el viaje.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
id |
string |
Opcional | Uno | 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, a medida que se desplaza en el sistema. Este ID no debe ser visible para el usuario final. Para eso, utiliza el campo label. |
label |
string |
Opcional | Uno | Etiqueta visible para el usuario; es decir, se debe mostrar al pasajero para ayudarlo a identificar el vehículo correcto. |
license_plate |
string |
Opcional | Uno | La placa 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. Se debe proporcionar, al menos, un especificador. Si se proporcionan varios, se deben interpretar como unidos por el operador lógico AND. Además, la combinación de especificadores debe coincidir con la información correspondiente del Feed GTFS. En otras palabras, para que una alerta se aplique a una entidad de GTFS, debe coincidir con todos los campos EntitySelector proporcionados. Por ejemplo, un EntitySelector que incluye los campos route_id: "5" y route_type: "3" se aplica solo al autobús que tiene route_id: "5", no a otras rutas con route_type: "3". Si un productor desea que una alerta se aplique a route_id: "5" y a route_type: "3", debe proporcionar dos campos EntitySelector separados: uno que haga referencia a route_id: "5" y otro que haga referencia a route_type: "3".
Se debe proporcionar, al menos, un especificador. En un EntitySelector, no pueden estar todos los campos vacíos.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
agency_id |
string |
Condicionalmente obligatorio | Uno | El agency_id del Feed GTFS al cual hace referencia este selector. |
route_id |
string |
Condicionalmente obligatorio | Uno | El route_id de GTFS al cual hace referencia este selector. Si se proporciona un direction_id, también se debe proporcionar un route_id. |
route_type |
int32 |
Condicionalmente obligatorio | Uno | El route_type de GTFS al cual hace referencia este selector. |
direction_id |
uint32 |
Condicionalmente obligatorio | Uno | Es el direction_id del archivo trips.txt del Feed GTFS, que se usa para seleccionar todos los viajes en una dirección para una ruta, especificada por el route_id. Si se proporciona un direction_id, también se debe proporcionar un route_id. |
trip |
TripDescriptor |
Condicionalmente obligatorio | Uno | La instancia de viaje de GTFS a la que hace referencia este selector. Este TripDescriptor debe resolverse en una sola instancia de viaje en los datos de GTFS (p. ej., un productor no puede proporcionar solo un trip_id para los viajes exact_times=0). Si el campo ScheduleRelationship se propaga en este TripDescriptor, los usuarios lo ignorarán cuando intenten identificar el viaje de GTFS. |
stop_id |
string |
Condicionalmente obligatorio | Uno | El stop_id del Feed GTFS al cual hace referencia este selector. |
message 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 procede de la siguiente manera: Si el idioma de la IU coincide con el código de idioma de una traducción, se elige la primera traducción coincidente. Si un idioma de IU predeterminado (p. ej., español) coincide con el código de idioma de una traducción; se elige la primera traducción coincidente. Si alguna traducción tiene un código de idioma no especificado, se elige esa traducción.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
translation |
Translation |
Obligatorio | Muchos | Se debe proporcionar, al menos, una traducción. |
mensaje Translation
Una cadena localizada asignada a un idioma.
Campos
| Nombre del campo | Tipo | Obligatorio | Cardinalidad | Descripción |
|---|---|---|---|---|
text |
string |
Obligatorio | Uno | Una string UTF-8 que incluye el mensaje |
language |
string |
Condicionalmente obligatorio | Uno | 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. Como máximo, una traducción puede tener una etiqueta de idioma no especificado. Si hay más de una traducción, es obligatorio indicar el idioma. |