Estensioni per l'acquisto di biglietti di Google Transit

Questa pagina definisce un sottoinsieme della specifica GTFS per la vendita di biglietti, che si trova nella 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 è obbligatorio.

Tipi di campi aggiuntivi

In questa sezione vengono descritti i tipi di campi aggiuntivi e quelli con estensioni di Google. Alcuni campi richiedono valori sotto forma di URI.

Estensioni o aggiunte di file

I file di testo con lo stato Estensione sono file già esistenti e che devono essere estesi. Devi aggiungere i nuovi campi da noi definiti nella seguente tabella.

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 fornite dopo la seguente tabella. 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.trip_ticketing_id e trips.ticketing_type.
stop_times.txt Estensione Aggiunge stop_times.ticketing_type.
ticketing_identifiers.txt Aggiunta Nuovo file. Per ulteriori dettagli, consulta Definizioni dei campi.
ticketing_deep_links.txt Aggiunta Nuovo file. Per ulteriori 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 questa route. 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 invece il valore trip_id.
ticketing_type Facoltativo

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

  • 0 o vuoto:
    • Se definisci un ticketing_deep_link_id per il percorso o l'azienda di trasporto, questo è disponibile.
    • Non disponibile negli altri casi.
  • 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 momento della fermata. Se definisci stop_times.ticketing_type, questo sostituisce il valore impostato in trip.ticketing_type.

  • Vuoto: utilizza il valore trip.ticketing_type.
  • 0:
    • Se definisci un ticketing_deep_link_id per il percorso o l'azienda di trasporto, questo è disponibile.
    • Non disponibile negli altri casi.
  • 1: non disponibile.

ticketing_identifiers.txt (file aggiunto)

Il caso più comune per la vendita di biglietti è che ogni fermata ha un identificatore per elaborare la fatturazione. Aziende diverse possono utilizzare lo stesso identificatore per una determinata fermata. Quando più aziende gestiscono la stessa fermata, ripeti la mappatura per ogni azienda.

Nome campo Presenza Dettagli
ticketing_stop_id Obbligatorio (ID) Definisce un ID per l'acquisto di biglietti predefinito per questa fermata per questa azienda.
stop_id Obbligatorio (ID da stops.txt) La fermata per la quale è definito il valore predefinito di ticketing_stop_id.
agency_id Obbligatorio (ID da agency.txt) L'agenzia della fermata per la quale è definito il valore predefinito di 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 i link diretti.

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

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

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

Per maggiori informazioni sui link diretti su Android, consulta la sezione Creare link diretti ai contenuti delle app.

Questo campo non è traducibile in 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 la sezione Link universali su iOS.

Questo campo non è traducibile in translations.txt.

Segnaposto di campo 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 della corsa.

Utilizza questo campo per la data di partenza della corsa dalla prima fermata.

Questo campo viene formattato come array JSON.
ticketing_trip_id

(ID da trips.txt, ripetibile) Identificatore della corsa.

Questo campo viene formattato come array JSON.
from_ticketing_stop_time_id

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

Per un determinato orario di fine, il valore è il seguente:

  • ticketing_stop_id definito in ticketing_identifiers.txt per agency_id e stop_id di stop_time.

  • In caso contrario, torna su stop_sequence.

Questo campo viene formattato come array JSON.
to_ticketing_stop_time_id

(Ripetibile) Identificatore del stop_time al quale termina la gamba.

Per una spiegazione sulla 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 in cui inizia la tratta.

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

Il valore temporale di questo campo è conforme alla norma ISO 8601 con il seguente formato di stringa:

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

Gli orari riportati di seguito sono gli stessi, in fusi orari diversi:

  • A Londra, Regno Unito: 2019-07-29T18:26:00+01:00
  • A NYC, USA-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, arrive_time allo stop_time in cui termina la tappa.

Il valore temporale di questo campo è conforme alla normativa ISO 8601 con il seguente formato di stringa:

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

Gli orari riportati di seguito sono gli stessi, in fusi orari diversi:

  • A Londra, Regno Unito: 2019-07-29T18:46:00+01:00
  • A NYC, US-NY: 2019-07-29T13:46:00-04:00
  • A Tokyo, JP: 2019-07-30T02:46:00+09:00

Questo campo viene formattato come array JSON.

Esempi

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

  • Il giorno del servizio 20190716, l'ID per la vendita di biglietti a tempo determinato ti1 inizia dall'ID 11 della vendita di biglietti a tempo di fermata all'ID 12. Il passeggero sale a bordo alle 14:00 UTC e arriva alle 14:50 UTC.
  • Il giorno del servizio 20190716, l'ID per la vendita di biglietti a tempo determinato ti2 inizia dall'ID 21 della vendita di biglietti a tempo di fermata all'ID 22. Il passeggero sale a bordo 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 questa corsa:

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 campo ticketing_identifiers.txt. I valori in grassetto sono quelli presenti nella chiamata web descritta dopo i file.

stop.txt

stop_id,stop_name

si1,"Parigi Gare-de-Lyon"

si2,"Lyon Part-Dieu"
routes.txt

route_id,route_long_name,ticketing_deep_link_id

ri1,"TGV nella città di Parigi-Lione",tdl1
trips.txt

trip_id, service_id, route_id, trip_short_name e ticketing_trip_id

ti1,ogni giorno,ri1,"TGV INOUI 6603",FR_SNCF_6603

ti2,ogni giorno,ri1,"TGV INOUI 6681",FR_SNCF_6681

ti3,ogni giorno,ri1,"TGV INOUI 6607",FR_SNCF_6607
stop_times.txt

trip_id, stop_sequence, stop_id, arrival_time e 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 e 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 del GTFS sono nel fuso orario UTC+1, allora seguente è la chiamata per il 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

Per implementare le estensioni per l'acquisto di biglietti di Google Transit, segui questi consigli:

Linee guida
Se possibile, condividi link diretti tra aziende di trasporto pubblico o percorsi.

Nel feed statico, ogni volta che più agenzie o route hanno gli stessi URL link diretti, devono condividere un singolo valore per il campo ticketing_deep_link_id. Ciò consente i trasferimenti tra agenzie o route.
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 per le fermate principali e 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 propagano tra un'interruzione principale e le relative interruzioni.
Mappa ticketing_stop_id per ogni azienda che utilizza la stessa fermata nel feed.

Nel feed statico, se più aziende che attivano la vendita di biglietti condividono la stessa fermata, la mappatura deve essere presente per ciascuna azienda.

Per maggiori dettagli, consulta la sezione Definizioni dei campi per ticketing_identifiers.txt.
Utilizza i link per app Android 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 link per app 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.