Estensioni per l'acquisto di biglietti di Google Transit

Questa pagina definisce un sottoinsieme della specifica GTFS-Ticketing, che è in fase di proposta durante la creazione di questo documento. Questa pagina include anche diverse limitazioni aggiuntive di Google.

Requisiti

Il campo departure_time in stop_times.txt è necessario.

Tipi di campi aggiuntivi

Questa sezione illustra i tipi di campi aggiuntivi e quelli con estensioni di Google. Alcuni campi richiedono valori sotto forma di URI.

  • URI: un URI (Uniform Resource Identifier) completamente qualificato che include lo schema. I caratteri speciali dell'URI devono utilizzare i caratteri di escape corretti. Per una descrizione di come creare valori URI completi, consulta RFC 3986 Uniform Resource Identifier (URI): Generic Syntax.

Estensioni o aggiunte di file

I file di testo con lo stato Extension sono file esistenti che devi estendere. Devi aggiungere i nuovi campi che definiamo nella tabella seguente.

I file di testo con lo stato Addition sono nuovi file introdotti dalle estensioni per l'acquisto di biglietti di Google Transit. Devi creare questi file in conformità alle definizioni dei campi riportate dopo la tabella seguente. Assicurati di includere questi file nel feed.

Nome file Stato Definisce
agency.txt Estensione Aggiunge agency.ticketing_deep_link_id.
routes.txt Estensione Aggiunge routes.ticketing_deep_link_id.
trips.txt Estensione Aggiunge trips.ticketing_trip_id e trips.ticketing_type.
stop_times.txt Estensione Aggiunge stop_times.ticketing_type.
ticketing_identifiers.txt Aggiunta Nuovo file. Per maggiori dettagli, consulta Definizioni dei campi.
ticketing_deep_links.txt Aggiunta Nuovo file. Per maggiori dettagli, consulta Definizioni dei campi.

Definizioni dei campi

agency.txt (file esteso)

Nome campo Presenza Dettagli
ticketing_deep_link_id Facoltativo

(ID da ticketing_deep_links.txt) definisce il link diretto da utilizzare per questa agenzia. Può essere sovrascritto in routes.txt.

routes.txt (file esteso)

Nome campo Presenza Dettagli
ticketing_deep_link_id Facoltativo (ID da ticketing_deep_links.txt) Definisce il link diretto da utilizzare per questo percorso. Se presente, sovrascrive il campo in agency.txt.

trips.txt (file esteso)

Nome campo Presenza Dettagli
ticketing_trip_id Facoltativo

(ID) Identificatore da passare nel link diretto. Non deve essere univoco.

Se ticketing_trip_id è vuoto, il sistema utilizza il valore di trip_id.
ticketing_type Facoltativo

(Enum) Definisce se la vendita di biglietti tramite un link diretto è disponibile per questa corsa:

  • 0 o vuoto:
    • Se definisci un ticketing_deep_link_id per la route o l'agenzia, questo valore è disponibile.
    • Non disponibile in caso contrario.
  • 1: non disponibile.

stop_times.txt (file esteso)

Nome campo Presenza Dettagli
ticketing_type Facoltativo

(Enum) Definisce se la vendita di biglietti tramite un link diretto è disponibile per questo orario di fermata. Se definisci stop_times.ticketing_type, questo sostituisce il valore impostato in trip.ticketing_type.

  • Vuoto: viene utilizzato il valore di trip.ticketing_type.
  • 0:
    • Se definisci un ticketing_deep_link_id per la route o l'agenzia, questo valore è disponibile.
    • Non disponibile in caso contrario.
  • 1: non disponibile.

ticketing_identifiers.txt (file aggiunto)

Il caso più comune per i biglietti è che ogni fermata abbia un identificatore per elaborare la fatturazione. Aziende diverse potrebbero utilizzare lo stesso identificatore per una determinata fermata. Quando più aziende operano nella stessa fermata, ripeti questa mappatura per ogni azienda.

Nome campo Presenza Dettagli
ticketing_stop_id Obbligatorio (ID) Definisce un ID biglietti predefinito per questa fermata per questa azienda.
stop_id Obbligatorio (ID da stops.txt) La fermata per cui è definito il valore predefinito ticketing_stop_id.
agency_id Obbligatorio (ID da agency.txt) L'azienda della fermata per cui è definito il valore predefinito ticketing_stop_id.

ticketing_deep_links.txt (file aggiunto)

Nome campo Presenza Dettagli
ticketing_deep_link_id Obbligatorio (ID) Definisce un ID per il link diretto.
web_url Facoltativo

(URL) L'URL da visitare per il link diretto.

Questo campo non è traducibile tramite translations.txt.
android_intent_uri Facoltativo

(URI) L'URI da passare a un'app Android nativa con un intent android.intent.action.VIEW.

Se è vuoto, significa che non puoi creare un link diretto a un'app Android nativa.

Per saperne di più sui link diretti su Android, consulta Creare link diretti ai contenuti dell'app.

Questo campo non è traducibile tramite translations.txt.
ios_universal_link_url Facoltativo

(URL) L'URL del link universale da richiamare su iOS.

Se è vuoto, i link diretti non vengono visualizzati su iOS.

Per ulteriori informazioni, consulta Link universali su iOS.

Questo campo non è traducibile tramite translations.txt.

Segnaposto dei campi nella chiamata API

Google chiama gli URL definiti in ticketing_deep_links.txt con i seguenti parametri:

Nome campo Dettagli
service_date

(Data, ripetibile) Giorno del servizio del viaggio.

Utilizza questo campo per la data di partenza del viaggio dalla prima fermata.

Questo campo viene formattato come array JSON.
ticketing_trip_id

(ID da trips.txt, ripetibile) Identificatore del viaggio.

Questo campo viene formattato come array JSON.
from_ticketing_stop_time_id

(Ripetitivo) Identificatore del stop_time in cui inizia la tappa.

Per una determinata ora di interruzione, il valore è il seguente:

  • Il ticketing_stop_id definito in ticketing_identifiers.txt per il agency_id e il stop_id del stop_time.

  • In caso contrario, si passa al valore stop_sequence.

Questo campo viene formattato come array JSON.
to_ticketing_stop_time_id

(Ripetitivo) Identificatore della stop_time in cui termina la tratta.

Per una spiegazione della derivazione del valore, consulta from_ticketing_stop_time_id.

Questo campo viene formattato come array JSON.
boarding_time

(ISO 8601, ripetibile) Ora di partenza, departure_time, del stop_time da cui inizia la tratta.

Utilizza questo campo per la data e l'ora effettive in cui il passeggero sale sul veicolo.

Il valore dell'ora di questo campo è conforme allo standard ISO 8601 con il seguente formato di stringa:

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

Tutte le ore riportate di seguito sono uguali, ma in fusi orari diversi:

  • A Londra, nel Regno Unito: 2019-07-29T18:26:00+01:00
  • A New York, US-NY: 2019-07-29T13:26:00-04:00
  • A Tokyo, Giappone: 2019-07-30T02:26:00+09:00

Questo campo viene formattato come array JSON.
arrival_time

(ISO 8601, ripetibile) Ora di arrivo, arrival_time all'ora stop_time in cui termina la tratta.

Il valore dell'ora di questo campo è conforme a ISO 8601 con il seguente formato di stringa:

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

Tutte le ore riportate di seguito sono uguali, ma in fusi orari diversi:

  • A Londra, nel Regno Unito: 29-07-2019T18:46:00+01:00
  • A New York, Stati Uniti: 2019-07-29T13:46:00-04:00
  • A Tokyo, Giappone: 2019-07-30T02:46:00+09:00

Questo campo viene formattato come array JSON.

Esempi

In questo esempio, le tratte del viaggio di un passeggero sono le seguenti:

  • Nella data di servizio 20190716, l'ID biglietto della corsa ti1 inizia dall'ID biglietto con orario di fermata 11 all'ID biglietto con orario di fermata 12. Il passeggero embarque alle 14:00 UTC e arriva alle 14:50 UTC.
  • Nella data di servizio 20190716, l'ID biglietto della corsa ti2 inizia dall'ID biglietto con orario di fermata 21 all'ID biglietto con orario di fermata 22. Il passeggero embarque alle 15:00 UTC e arriva alle 15:50 UTC.

Per questo esempio, web_url è https://examplepetstore.com.

Date tutte queste informazioni, utilizza i seguenti valori per i parametri del feed per questo viaggio:

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

Di seguito è riportato l'URI finale dopo la codifica:

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

Esempi di valori ticketing_stop_id diversi

Le fermate possono avere ID diversi ai fini della vendita di biglietti con il ticketing_identifiers.txt campo. I valori in grassetto sono quelli trovati nella chiamata web descritta dopo i file.

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

Se la richiesta viene effettuata il 19/07/2019 e gli orari GTFS sono nel fuso orario UTC+1, la chiamata per il web è la seguente:

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

Segui questi consigli per implementare le estensioni per l'acquisto di biglietti di Google Transit:

Linee guida
Condividi link diretti tra aziende o percorsi, se possibile.

Nel feed statico, quando più aziende o percorsi hanno gli stessi URL dei link diretti, devono condividere un unico valore per il campo ticketing_deep_link_id. In questo modo è possibile effettuare trasferimenti tra aziende o percorsi.
Imposta valori coerenti per ticketing_type.

Il valore ticketing_type per una determinata fermata deve essere coerente in tutte le righe del file stop_times.txt.
Mappa ticketing_stop_id sia per le fermate principali che per quelle secondarie. Esegui la mappatura di tutte le fermate principali e secondarie che richiedono l'acquisto di biglietti. Nel file ticketing_identifiers.txt, i valori ticketing_stop_id non si propaggono tra una fermata principale e le sue secondarie.
Mappa ticketing_stop_id per ogni azienda che utilizza la stessa fermata nel feed.

Nel feed statico, se più aziende che consentono l'acquisto di biglietti condividono la stessa fermata, la mappatura deve essere presente per ciascuna azienda.

Per ulteriori dettagli, consulta la sezione Definizioni dei campi per ticketing_identifiers.txt.
Utilizza Android App Links quando è necessario un link diretto a un'app per Android.

Se il partner vuole aprire un'app per Android da un link diretto, configura il link diretto come un link a un'app per Android.
Utilizza i link universali per iOS quando è necessario un link diretto a un'app per iOS. Se il partner vuole aprire un'app per iOS da un link diretto, configura il link diretto come link universale per iOS.