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.trip_ticketing_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.

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.

Si ticketing_trip_id está vacío, el sistema usa 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

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.
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.

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.

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.

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.

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.

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.

  • 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.

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: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

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

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 día 19/07/2019 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

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.
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.
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.
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.