Extensiones de venta de boletos de Google Transit

En esta página, se define un subconjunto de la especificación de venta de boletos de GTFS, que se encuentra en la etapa de propuesta durante la creación de este documento. También se incluyen aquí varias restricciones adicionales de Google.

Requisitos

El campo departure_time en stop_times.txt es necesario.

Tipos de campos adicionales

En esta sección, se describen los tipos de campos adicionales y aquellos que incluyen extensiones de Google. Algunos campos requieren valores con el formato de un URI.

• URI: Un identificador uniforme de recursos (URI) completamente calificado que incluye el esquema. Todos los caracteres especiales del URI deben usar los caracteres de escape correctos. Para obtener una descripción de cómo crear valores de URI completamente calificados, consulta el documento RFC 3986 Uniform Resource Identifier (URI): Generic Syntax (Identificador uniforme de recursos (URI) de RFC 3986: Sintaxis genérica).

Adiciones o extensiones de archivo

Los archivos de texto con el estado Extension son archivos que ya existen y que debes extender. Debes agregar los campos nuevos que definimos en la siguiente tabla.

Los archivos de texto con el estado Addition son archivos nuevos ingresados por las extensiones de venta de boletos de Google Transit. Debes crear estos archivos de acuerdo con las definiciones de campos que se proporcionan después de la siguiente tabla. Asegúrate de incluir estos archivos en tu feed.

Nombre del archivo	Estado	Definiciones
agency.txt	Extension	Agrega agency.ticketing_deep_link_id.
routes.txt	Extension	Agrega routes.ticketing_deep_link_id.
trips.txt	Extension	Agrega trips.ticketing_trip_id y trips.ticketing_type.
stop_times.txt	Extension	Agrega stop_times.ticketing_type.
ticketing_identifiers.txt	Addition	Nuevo archivo. Para obtener más detalles, consulta Definiciones de campos.
ticketing_deep_links.txt	Addition	Nuevo archivo. Para obtener más detalles, consulta Definiciones de campos.

Definiciones de campos

agency.txt (archivo extendido)

Nombre del campo	Presencia	Detalles
ticketing_deep_link_id	Opcional	(ID de ticketing_deep_links.txt). Define el vínculo directo que se usará para esta empresa. Se puede reemplazar en routes.txt. Nota: Para aplicar la venta de boletos a todo el feed estático, establece el mismo valor en el campo ticketing_deep_link_id para todas las empresas del archivo agency.txt.

routes.txt (archivo extendido)

Nombre del campo	Presencia	Detalles
ticketing_deep_link_id	Opcional	(ID de ticketing_deep_links.txt). Define el vínculo directo que se usará en esta ruta. Si está presente, reemplaza el campo en agency.txt.

trips.txt (archivo extendido)

Nombre del campo	Presencia	Detalles
ticketing_trip_id	Opcional	(ID). Identificador para pasar en el vínculo directo. No tiene que ser único. If ticketing_trip_id está vacío, el sistema utilizará el valor de trip_id en su lugar.
ticketing_type	Opcional	(Enum). Define si este viaje incluye generación de boletos a través de un vínculo directo: 0 o vacío: Lo incluirá si defines un ticketing_deep_link_id para la ruta o empresa. De lo contrario, no lo incluirá. 1: No disponible

stop_times.txt (archivo extendido)

Nombre del campo	Presencia	Detalles
ticketing_type	Opcional	(Enum). Define si la generación de boletos a través de un vínculo directo está disponible para este horario de parada. Si defines stop_times.ticketing_type, esto anula el valor establecido en trip.ticketing_type. Vacío: Usa el valor de trip.ticketing_type. 0: Lo incluirá si defines un ticketing_deep_link_id para la ruta o empresa. De lo contrario, no lo incluirá. 1: No disponible Importante: Para un stop_id particular, si cualquiera de sus stop_times tiene el código ticketing_type=1, todas las demás stop_times también deben tener ticketing_type=1.

ticketing_identifiers.txt (archivo agregado)

El caso más común para la generación de boletos es que cada parada tenga un identificador para procesar la facturación. Es posible que diferentes empresas utilicen el mismo identificador para cualquier parada determinada. Cuando varias empresas prestan servicio en la misma parada, repite esta asignación para cada empresa.

Nombre del campo	Presencia	Detalles
ticketing_stop_id	Obligatorio	(ID). Define un ID predeterminado de generación de boletos correspondiente a esta parada de esta empresa.
stop_id	Obligatorio	(ID de stops.txt) La parada para la cual se define el ticketing_stop_id predeterminado.
agency_id	Obligatorio	(ID de agency.txt): La empresa de la parada para la que se define el valor predeterminado de ticketing_stop_id.

ticketing_deep_links.txt (archivo agregado)

Nombre del campo	Presencia	Detalles
ticketing_deep_link_id	Obligatorio	(ID). Define un ID para el vínculo directo.
web_url	Opcional	(URL). La URL que se visitará para los vínculos directos. Este campo no se puede traducir a través de translations.txt. Importante: No se admite la traducción de URL para este campo, por lo que la detección de idiomas deben realizarla el sitio web o la app receptores.
android_intent_uri	Opcional	(URI). Es el URI que se pasará a una app para Android nativa con un intent android.intent.action.VIEW. Si este campo está vacío, significa que no puedes crear un vínculo directo a una app para Android nativa. Importante: No se admite la traducción de URL para este campo, por lo que la detección de idiomas deben realizarla el sitio web o la app receptores. Para obtener más información sobre los vínculos directos en Android, consulta Cómo crear vínculos directos al contenido de la app. Recomendación: Usa Android App Links, que son más seguros y tienen un mejor comportamiento de resguardo si el pasajero no tiene la app para Android nativa en su dispositivo. Este campo no se puede traducir a través de translations.txt.
ios_universal_link_url	Opcional	(URL). La URL del vínculo universal que se invocará en iOS. Importante: No se admite la traducción de URL para este campo, por lo que la detección de idiomas deben realizarla el sitio web o la app receptores. Si este campo está vacío, el vínculo directo no se mostrará en iOS. Para obtener más información, consulta esta página sobre los vínculos universales en iOS. Este campo no se puede traducir a través de translations.txt.

Nota: Cuando varias empresas o rutas comparten las mismas URLs de vínculos directos en el feed, te recomendamos que definas solo un vínculo directo y vincules todos esas empresas o rutas hacia el mismo vínculo directo. Para obtener más información, consulta la sección Prácticas recomendadas.

Marcadores de posición de campo en la llamada a la API

Google llama a las URLs definidas en ticketing_deep_links.txt con los siguientes parámetros:

Nombre del campo	Detalles
service_date	(Fecha, repetible). Día de servicio del viaje. Usa este campo para la fecha de inicio del viaje desde su primera parada. Este campo tiene el formato de un array JSON.
ticketing_trip_id	(ID de trips.txt, repetible). Es el identificador del viaje. Este campo tiene el formato de un array JSON.
from_ticketing_stop_time_id	(Repetible). Es el identificador de stop_time en el que comienza el tramo. Para un horario de parada en particular, el valor es el siguiente: El ticketing_stop_id definido en el archivo ticketing_identifiers.txt para el agency_id y el stop_id del stop_time. Importante: Esto solo usa los ticketing_identifiers correspondientes a la parada en sí. Incluso si esa parada tiene otra principal, omitimos los ticketing_identifiers de la parada principal. De lo contrario, se utiliza stop_sequence. Este campo tiene el formato de un array JSON.
to_ticketing_stop_time_id	(Repetible). Es el identificador de la stop_time en la que termina el tramo. Consulta from_ticketing_stop_time_id para obtener una explicación de cómo se deriva el valor. Este campo tiene el formato de un array JSON.
boarding_time	(ISO 8601, repetible). Hora de salida (departure_time) de la stop_time en la que comienza el tramo. Usa este campo para la fecha y hora reales en las que el pasajero se sube al vehículo. El valor de hora de este campo cumple con la norma ISO 8601 y usa el siguiente formato de cadena: YYYY-MM-DDThh:mm:ss±hh:mm Todos los horarios que aparecen a continuación expresan la misma hora, pero en diferentes zonas horarias: En Londres, Reino Unido: 2019-07-29T18:26:00+01:00 En Nueva York, EE.UU.: 2019-07-29T13:26:00-04:00 En Tokio, Japón: 2019-07-30T02:26:00+09:00 Importante: La zona horaria no es necesariamente la misma que la de la empresa del feed. La zona horaria se expresa en UTC. Este campo tiene el formato de un array JSON.
arrival_time	(ISO 8601, repetible). Hora de llegada (arrival_time) a la stop_time en la que termina el tramo. El valor de tiempo de este campo cumple con la norma ISO 8601 y usa la siguiente cadena de formato: YYYY-MM-DDThh:mm:ss±,hh:mm Todos los horarios que aparecen a continuación expresan la misma hora, pero en diferentes zonas horarias: En Londres, Reino Unido: 2019-07-29T18:46:00+01:00 En Nueva York, EE.UU.: 2019-07-29T13:46:00-04:00 En Tokio, Japón: 2019-07-30T02:46:00+09:00 Importante: La zona horaria no es necesariamente la misma que la de la empresa del feed. La zona horaria se expresa en UTC. Este campo tiene el formato de un array JSON.

Ejemplos

En este ejemplo, los tramos del recorrido de un pasajero son los siguientes:

• En la fecha de servicio 20190716, el ID de generación de boletos ti1 del viaje comienza en la hora de parada con el ID de generación de boletos 11 y va hasta la hora de parada con el ID de generación de boletos 12. El pasajero sube a las 2:00 p.m. UTC y llega a las 2:50 p.m. UTC.
• En la fecha de servicio 20190716, el ID de generación de boletos ti2 del viaje comienza en la hora de parada con el ID de generación de boletos 21 y va hasta la hora de parada con el ID de generación de boletos 22. El pasajero sube a las 3:00 p.m. UTC y llega a las 3:50 p.m. UTC.

Para este ejemplo, la web_url es https://examplepetstore.com.

Con toda esta información, usa los siguientes valores para los parámetros del feed de este viaje:

Nombre del campo	Detalles
service_date	["20190716", "20190716"]
ticketing_trip_id	["ti1", "ti2"]
from_ticketing_stop_time_id	["11", "21"]
to_ticketing_stop_time_id	["12", "22"]
boarding_time	["2019-07-16T14:00:00+00:00", "2019-07-16T15:00:00+00:00"]
arrival_time	["2019-07-16T14:50:00+00:00", "2019-07-16T15:50:00+00:00"]

A continuación, se muestra el URI final después de la codificación:

https://examplepetstore.com?service_date=%5B%2220190716%22,%2220190716%22%5D &ticketing_trip_id=%5B%22ti1%22,%22ti2%22%5D&from_ticketing_stop_time_id=%5B%2211%22,%2221%22%5D &to_ticketing_stop_time_id=%5B%2212%22,%2222%22%5D&boarding_time=%5B%222019-07-16T14:00:00%2B00:00 %22,%222019-07-16T15:00:00%2B00:00%22%5D&arrival_time=%5B%222019-07-16T14:50:00%2B00:00 %22,%222019-07-16T15:50:00%2B00:00%22%5D

Ejemplos de diferentes valores de ticketing_stop_id

Las paradas pueden tener diferentes ID a fin de generar boletos con el campo ticketing_identifiers.txt. Los valores en negrita son los que se encuentran en la llamada web que se describe a continuación de los archivos.

stop.txt
stop_id,stop_name si1,“Paris Gare-de-Lyon” si2,"Lyon Part-Dieu"

routes.txt
route_id,route_long_name,ticketing_deep_link_id ri1,“TGV inOui Paris-Lyon”,tdl1

trips.txt
trip_id,service_id,route_id,trip_short_name, ticketing_trip_id ti1,everyday,ri1,"TGV INOUI 6603",FR_SNCF_6603 ti2,everyday,ri1,"TGV INOUI 6681",FR_SNCF_6681 ti3,everyday,ri1,"TGV INOUI 6607",FR_SNCF_6607

stop_times.txt
trip_id,stop_sequence,stop_id,arrival_time, departure_time ti1,1,si1,06:59:00,06:59:00 ti1,2,si2,08:56:00,08:56:00 ti2,1,si1,07:53:00,07:53:00 ti2,2,si2,10:00:00,10:00:00 ti3,1,si1,08:59:00,08:59:00 ti3,2,si2,10:56:00,10:56:00

ticketing_identifiers.txt
stop_id,agency_id,ticketing_stop_id si1,agency1,4924 si2,agency1,4676

ticketing_deep_links.txt
ticketing_deep_link_id, web_url, android_intent_uri, ios_universal_link_url tdl1, https://examplepetstore.com/api/gtfs/web, https://examplepetstore.com/api/gtfs/android, https://examplepetstore.com/api/gtfs/ios

Si la solicitud se realizó el 2019-07-19 y los horarios de GTFS se encuentran en la zona horaria UTC+1, la llamada para la Web es la siguiente:

https://examplepetstore.com/api/gtfs/web?service_date=%5B%2220190719%22%5D&ticketing_trip_id= %5B%22FR_SNCF_6603%22%5D&from_ticketing_stop_time_id=%5B%224924%22%5D&to_ticketing_stop_time_id= %5B%224676%22%5D&boarding_time=%5B%222019-07-19T05:59:00%2B00:00%22%5&arrival_time=%5B%222019-07-19T07:56:00%2B00:00%22%5D

Importante: Ten en cuenta que los valores presentes en boarding_time y en arrival_time, que están en UTC, no necesariamente siguen la zona horaria de GTFS (UTC+1), lo que provoca un cambio en el valor HH:MM:SS.

Prácticas recomendadas

Sigue estas recomendaciones para implementar las extensiones de venta de boletos de Google Transit:

Lineamientos
Comparte vínculos directos entre empresas o rutas siempre que sea posible.	En el feed estático, siempre que varias empresas o rutas tengan las mismas URLs de vínculos directos, deben compartir el mismo valor para el campo ticketing_deep_link_id. Esto permite transbordos entre empresas o rutas. Nota: Si no es así, los pasajeros deben comprar dos boletos separados debido a los diferentes valores en ticketing_deep_link_id.
Establece valores constantes para ticketing_type.	El valor ticketing_type de una parada en particular debe ser el mismo en todas las filas del archivo stop_times.txt. Nota: Un valor ticketing_type de 1 inhabilita la generación de boletos en todos los viajes que usan esa parada en particular.
Asigna ticketing_stop_id tanto para las paradas principales como para las secundarias.	Debes asignar este valor a todas las paradas principales y secundarias que requieran generación de boletos. En el archivo ticketing_identifiers.txt, los valores de ticketing_stop_id no se propagan entre una parada principal y sus elementos secundarios.
Asigna ticketing_stop_id para cada empresa que usa la misma parada en el feed.	En el feed estático, si varias empresas que habilitan la generación de boletos comparten la misma parada, la asignación debe estar presente para cada una de las empresas. Para obtener más detalles, consulta la sección Definiciones de campos de ticketing_identifiers.txt.
Usa Android App Links cuando se requiera un vínculo directo a una app para Android.	Si el socio quiere abrir una app para Android desde un vínculo directo, configura el vínculo directo como Android App Link. Nota: Si el socio solo desea abrir un sitio web habilitado para dispositivos móviles, usa directamente la URL del sitio web.
Usa los vínculos universales de iOS cuando necesites un vínculo directo a una app para iOS.	Si el socio quiere abrir una app para iOS desde un vínculo directo, configúralo como un vínculo universal de iOS.