Extensões de venda de passagens do Google Transit

Nesta página, definimos um subconjunto da especificação de passagens da GTFS, que está na fase proposta durante a criação deste documento. Esta página também inclui várias outras restrições do Google.

Requisitos

O campo departure_time em stop_times.txt é obrigatório.

Outros tipos de campos

Nesta seção, descrevemos os outros tipos de campos e aqueles com extensões do Google. Alguns campos exigem valores na forma de URI.

Adições ou extensões de arquivo

Os arquivos de texto com o estado Extensão já existem e precisam ser estendidos. É necessário adicionar os novos campos definidos na tabela a seguir.

Os arquivos de texto com o estado Adição são novos arquivos introduzidos pelas extensões de venda de passagens do Google Transit. Você precisa criar esses arquivos de acordo com as definições de campo fornecidas após a tabela a seguir. Inclua esses arquivos no seu feed.

Nome do arquivo Estado Define
agency.txt Extensão Adiciona agency.ticketing_deep_link_id.
routes.txt Extensão Adiciona routes.ticketing_deep_link_id.
trips.txt Extensão Adiciona trips.ticketing_trip_id e trips.ticketing_type.
stop_times.txt Extensão Adiciona stop_times.ticketing_type.
ticketing_identifiers.txt Adição Novo arquivo. Para mais detalhes, consulte Definições dos campos.
ticketing_deep_links.txt Adição Novo arquivo. Para mais detalhes, consulte Definições dos campos.

Definições dos campos

agency.txt (arquivo estendido)

Nome do campo Presença Detalhes
ticketing_deep_link_id Opcional

(ID de ticketing_deep_links.txt) Define o link direto que será usado com a empresa. Pode ser substituído em routes.txt.

routes.txt (arquivo estendido)

Nome do campo Presença Detalhes
ticketing_deep_link_id Opcional (ID de ticketing_deep_links.txt) Define o link direto que será usado no trajeto. Se presente, substitui o campo em agency.txt.

trips.txt (arquivo estendido)

Nome do campo Presença Detalhes
ticketing_trip_id Opcional

(ID) Identificador para transmitir no link direto. Não precisa ser único.

Se ticketing_trip_id estiver vazio, o sistema vai usar o valor de trip_id.
ticketing_type Opcional

(Tipo enumerado) Defina se a venda de passagens por um link direto está disponível para essa viagem:

  • 0 ou vazio:
    • Se você definir um ticketing_deep_link_id para o trajeto ou a empresa, a venda vai estar disponível.
    • Caso contrário, ficará indisponível.
  • 1: indisponível.

stop_times.txt (arquivo estendido)

Nome do campo Presença Detalhes
ticketing_type Opcional

(Tipo enumerado) Define se a venda de passagens por link direto está disponível para esse horário de parada. Se você definir stop_times.ticketing_type, isso vai substituir o valor definido em trip.ticketing_type.

  • Vazio: usa o valor de trip.ticketing_type.
  • 0:
    • Se você definir um ticketing_deep_link_id para o trajeto ou a empresa, a venda vai estar disponível.
    • Caso contrário, ficará indisponível.
  • 1: indisponível.

Arquivo ticketing_identifiers.txt: adicionado.

O caso mais comum de venda de ingressos é que cada parada tem um identificador para processar o faturamento. Agências diferentes podem usar o mesmo identificador para qualquer parada. Quando várias agências atendem à mesma parada, repita esse mapeamento para cada uma delas.

Nome do campo Presença Detalhes
ticketing_stop_id Obrigatório (ID) Define um ID padrão de venda de passagens da empresa para essa parada.
stop_id Obrigatório (ID de stops.txt) A parada em que o ticketing_stop_id padrão é definido.
agency_id Obrigatório (ID de agency.txt) A empresa da parada para a qual o ticketing_stop_id padrão é definido.

Arquivo ticketing_deep_links.txt: adicionado.

Nome do campo Presença Detalhes
ticketing_deep_link_id Obrigatório (ID) Define um ID para o link direto.
web_url Opcional

(URL) O URL que será acessado para links diretos.

Esse campo não pode ser traduzido por translations.txt.
android_intent_uri Opcional

(URI) O URI que será transmitido para um app Android nativo com uma intent android.intent.action.VIEW.

Se estiver vazio, isso significa que não é possível criar links diretos para um app desses.

Para mais detalhes sobre os links diretos no Android, consulte Criar links diretos para conteúdo de app.

Esse campo não pode ser traduzido por translations.txt.
ios_universal_link_url Opcional

(URL) O URL universal do link que será invocado no iOS.

Se estiver vazio, o link direto não vai aparecer no iOS.

Para mais informações, consulte Links universais no iOS (em inglês).

Esse campo não pode ser traduzido por translations.txt.

Marcadores de campo na chamada de API

O Google chama os URLs definidos em ticketing_deep_links.txt com os seguintes parâmetros:

Nome do campo Detalhes
service_date

(Data, repetível) Dia do serviço da viagem.

Use esse campo para a data em que a viagem parte da primeira parada.

Esse campo é formatado como uma matriz JSON.
ticketing_trip_id

(ID de trips.txt, repetível) Identificador da viagem.

Esse campo é formatado como uma matriz JSON.
from_ticketing_stop_time_id

(Repetível) Identificador do stop_time em que o trecho começa.

Para um horário de parada específico, o valor é o seguinte:

  • O ticketing_stop_id definido em ticketing_identifiers.txt para o agency_id e o stop_id de stop_time.

  • Caso contrário, ele volta na stop_sequence.

Esse campo é formatado como uma matriz JSON.
to_ticketing_stop_time_id

(Repetível) Identificador do stop_time em que o trecho termina.

Para uma explicação sobre a derivação do valor, consulte from_ticketing_stop_time_id.

Esse campo é formatado como uma matriz JSON.
boarding_time

(ISO 8601, repetível) Horário de partida (departure_time) do stop_time em que o trecho começa.

Use esse campo para informar a data e hora quando o passageiro embarca no veículo.

O valor do horário desse campo segue a ISO 8601, com o formato de string a seguir:

YYYY-MM-DDThh:mm:ss±hh:mm

Todos os horários abaixo são iguais, em fusos horários diferentes:

  • Em Londres, Reino Unido: 2019-07-29T18:26:00+01:00
  • Em Nova York, EUA: 2019-07-29T13:26:00-04:00
  • Em Tóquio, Japão: 2019-07-30T02:26:00+09:00

Esse campo é formatado como uma matriz JSON.
arrival_time

(ISO 8601, repetível) Horário de chegada; arrival_time no stop_time em que o trecho termina.

O valor do horário desse campo segue a ISO 8601, com o formato de string a seguir:

YYYY-MM-DDThh:mm:ss±,hh:mm

Todos os horários abaixo são iguais, em fusos horários diferentes:

  • Em Londres, Reino Unido: 2019-07-29T18:46:00+01:00
  • Em Nova York, EUA: 2019-07-29T13:46:00-04:00
  • Em Tóquio, Japão: 2019-07-30T02:46:00+09:00

Esse campo é formatado como uma matriz JSON.

Exemplos

No exemplo, estes são os trechos da jornada de um passageiro:

  • Na data de serviço 20190716, o ID de passagem da viagem ti1 começa com 11 e termina com 12 (considerando os horários das paradas). O passageiro embarca às 14h UTC e chega às 14h50 UTC.
  • Na data de serviço 20190716, o ID de passagem da viagem ti2 começa com 21 e termina com 22 (considerando os horários das paradas). O passageiro embarca às 15h UTC e chega às 15h50 UTC.

Nesse exemplo, web_url é https://examplepetstore.com.

Com todas essas informações, use os seguintes valores nos parâmetros do feed dessa viagem:

Nome do campo Detalhes
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"]

Confira a seguir o URI final após a codificação:

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

Exemplos de valores ticketing_stop_id diferentes

As paradas podem ter IDs diferentes para a venda de passagens no campo ticketing_identifiers.txt. Os valores em negrito são aqueles encontrados na chamada da Web descrita após os arquivos.

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 em Oui Paris-Lyon",tdl1
trips.txt

trip_id,service_id,route_id,trip_short_name, ticketing_trip_id

ti1,todos os dias,ri1,"TGV INOUI 6603",FR_SNCF_6603

ti2,todos os dias,ri1,"TGV INOUI 6681",FR_SNCF_6681

ti3,todos os dias,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,agência1,4924

si2,empresa1,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

Se a solicitação for feita em 19/07/2019, e os horários da GTFS estiverem no fuso horário UTC+1, esta será a chamada para a Web:

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

Siga estas recomendações para implementar as extensões de venda de passagens do Google Transit:

Diretrizes
Compartilhe links diretos entre empresas ou trajetos sempre que possível.

No feed estático, sempre que várias empresas ou trajetos têm os mesmos URLs de link direto, eles precisam compartilhar um único valor para o campo ticketing_deep_link_id. Isso permite transferências entre empresas ou trajetos.
Defina valores consistentes para ticketing_type.

O valor de ticketing_type para uma parada específica precisa ser consistente em todas as linhas no arquivo stop_times.txt.
Mapeie ticketing_stop_id para as paradas principais e secundárias. Faça o mapeamento de todas as paradas principais e secundárias que exigem a venda de passagens. No arquivo ticketing_identifiers.txt, os valores de ticketing_stop_id não são propagados entre uma parada principal e as secundárias.
Mapeie ticketing_stop_id para cada agência que usa a mesma parada no feed.

No feed estático, se várias empresas que vendem passagens compartilharem a mesma parada, o mapeamento terá que estar presente em todas elas.

Para mais detalhes, consulte a seção Definições dos campos de ticketing_identifiers.txt.
Use Links do app Android quando um link direto for necessário para um app Android.

Se o parceiro quiser abrir um aplicativo desses usando um link direto, configure como um Link do app Android.
Use links universais no iOS quando um link direto for necessário para um app iOS. Se o parceiro quiser abrir um aplicativo desses usando um link direto, configure como um link universal para iOS.