Extensions de billetterie dans Google Transports en commun

Cette page définit un sous-ensemble de la spécification GTFS-Ticketing, qui est à l'état de proposition au moment de la rédaction de ce document. Cette page inclut également plusieurs restrictions Google supplémentaires.

Conditions requises

Le champ departure_time dans stop_times.txt est obligatoire.

Types de champs supplémentaires

Cette section décrit les types de champs supplémentaires, ainsi que ceux associés aux extensions de Google. Certains champs requièrent des valeurs sous la forme d'un URI.

• URI : Uniform Resource Identifier (identifiant de ressource uniforme) complet incluant le schéma. Tous les caractères spéciaux de l'URI doivent utiliser les caractères d'échappement appropriés. Pour savoir comment créer des valeurs d'URI complets, consultez RFC 3986 Uniform Resource Identifier (URI): Generic Syntax.

Ajouts ou extensions de fichiers

Les fichiers texte avec l'état Extension sont des fichiers qui existent déjà et que vous devez étendre. Vous devez ajouter les nouveaux champs définis dans le tableau suivant.

Les fichiers texte avec l'état Ajout sont de nouveaux fichiers introduits par les extensions de billetterie Google Transports en commun. Vous devez créer ces fichiers conformément aux définitions des champs fournies après le tableau suivant. N'oubliez pas d'inclure ces fichiers dans votre flux.

Nom de fichier	État	Définit
agency.txt	Extension	Ajoute agency.ticketing_deep_link_id.
routes.txt	Extension	Ajoute routes.ticketing_deep_link_id.
trips.txt	Extension	Ajoute trips.trip_ticketing_id et trips.ticketing_type.
stop_times.txt	Extension	Ajoute stop_times.ticketing_type.
ticketing_identifiers.txt	Ajout	Nouveau fichier. Pour en savoir plus, consultez Définition des champs.
ticketing_deep_links.txt	Ajout	Nouveau fichier. Pour en savoir plus, consultez Définition des champs.

Définition des champs

agency.txt (fichier étendu)

Nom du champ	Présence	Détails
ticketing_deep_link_id	Facultatif	(ID de ticketing_deep_links.txt) Définit le lien profond à utiliser pour cette agence. Peut être remplacé dans routes.txt. Remarque : Pour appliquer la billetterie à l'ensemble du flux statique, définissez la même valeur dans le champ ticketing_deep_link_id pour toutes les agences du fichier agency.txt.

routes.txt (fichier étendu)

Nom du champ	Présence	Détails
ticketing_deep_link_id	Facultatif	(ID issu de ticketing_deep_links.txt) Définit le lien profond à utiliser pour cet itinéraire. S'il est présent, il remplace le champ de agency.txt.

trips.txt (fichier étendu)

Nom du champ	Présence	Détails
ticketing_trip_id	Facultatif	(ID) Identifiant à transmettre via le lien profond. N'a pas besoin d'être unique. Si ticketing_trip_id est vide, le système utilise plutôt la valeur de trip_id.
ticketing_type	Facultatif	(Enum) Indique si la billetterie via un lien profond est disponible pour ce trajet : 0 ou vide : Cette option est disponible si vous définissez un ticketing_deep_link_id pour l'itinéraire ou l'agence. Sinon, elle ne l'est pas. 1 : non disponible.

stop_times.txt (fichier étendu)

Nom du champ	Présence	Détails
ticketing_type	Facultatif	(Enum) Indique si la billetterie via un lien profond est disponible pour cet arrêt. Si vous définissez stop_times.ticketing_type, cette valeur remplace celle définie dans trip.ticketing_type. Vide : utilise la valeur de trip.ticketing_type. 0 : Cette option est disponible si vous définissez un ticketing_deep_link_id pour l'itinéraire ou l'agence. Sinon, elle ne l'est pas. Important : Pour un stop_id spécifique, si l'un de ses stop_times inclut ticketing_type=1, alors tous ses autres stop_times doivent aussi avoir ticketing_type=1.

ticketing_identifiers.txt (fichier ajouté)

Dans la plupart des cas de billetterie, chaque arrêt présente un identifiant pour la facturation. Différentes agences peuvent utiliser le même identifiant pour un arrêt donné. Lorsque plusieurs agences desservent le même arrêt, répétez ce mappage pour chacune d'elles.

Nom du champ	Présence	Détails
ticketing_stop_id	Obligatoire	(ID) Définit un ID de billetterie par défaut pour cet arrêt et cette agence.
stop_id	Obligatoire	(ID issu de stops.txt) Arrêt pour lequel le ticketing_stop_id par défaut est défini.
agency_id	Obligatoire	(ID issu de agency.txt) Agence de l'arrêt pour lequel le ticketing_stop_id par défaut est défini.

ticketing_deep_links.txt (fichier ajouté)

Nom du champ	Présence	Détails
ticketing_deep_link_id	Obligatoire	(ID) Définit un ID pour le lien profond.
web_url	Facultatif	(URL) URL de destination pour les liens profonds. Ce champ ne peut pas être traduit via translations.txt. Important : La traduction des URL n'est pas acceptée pour ce champ. La détection de la langue doit donc être effectuée par le site Web ou l'application destinataire.
android_intent_uri	Facultatif	(URI) URI à transmettre à une application Android native avec un intent android.intent.action.VIEW. S'il est vide, cela signifie que vous ne pouvez pas créer de lien profond vers une application Android native. Important : La traduction des URL n'est pas acceptée pour ce champ. La détection de la langue doit donc être effectuée par le site Web ou l'application destinataire. Pour en savoir plus sur les liens profonds sur Android, consultez Créer des liens profonds vers le contenu d'une application. Recommandation : Utilisez les liens Android App Links. Ils sont plus sécurisés et offrent un meilleur comportement de remplacement lorsque le passager n'a pas installé l'application Android native sur son appareil. Ce champ ne peut pas être traduit via translations.txt.
ios_universal_link_url	Facultatif	(URL) URL du lien universel à appeler sur iOS. Important : La traduction des URL n'est pas acceptée pour ce champ. La détection de la langue doit donc être effectuée par le site Web ou l'application destinataire. Si ce champ est vide, les liens profonds ne s'afficheront pas sur iOS. Pour en savoir plus, consultez Liens universels sur iOS. Ce champ ne peut pas être traduit via translations.txt.

Remarque : Lorsque plusieurs agences ou itinéraires partagent les mêmes URL de liens profonds dans le flux, nous vous recommandons vivement de ne définir qu'un seul lien profond et d'y associer l'ensemble de ces agences ou itinéraires. Pour en savoir plus, consultez la section Pratiques recommandées.

Espaces réservés des champs dans l'appel d'API

Google appelle les URL définies dans ticketing_deep_links.txt avec les paramètres suivants :

Nom du champ	Détails
service_date	(Date, reproductible) Jour de service du trajet. Ce champ est formaté comme un tableau JSON.
ticketing_trip_id	(ID issu de trips.txt, reproductible) Identifiant du trajet. Ce champ est formaté comme un tableau JSON.
from_ticketing_stop_time_id	(Reproductible) Identifiant du stop_time auquel commence l'étape. Pour une heure d'arrêt particulière, la valeur est la suivante : ticketing_stop_id défini dans ticketing_identifiers.txt pour l'agency_id et le stop_id du stop_time. Important : Seuls les ticketing_identifiers pour l'arrêt lui-même sont utilisés. Même si l'arrêt a un arrêt parent, nous ignorons les ticketing_identifiers de celui-ci. Sinon, la stop_sequence est utilisée. Ce champ est formaté comme un tableau JSON.
to_ticketing_stop_time_id	(Reproductible) Identifiant du stop_time auquel se termine l'étape. Pour en savoir plus sur la dérivation de la valeur, consultez from_ticketing_stop_time_id. Ce champ est formaté comme un tableau JSON.
boarding_time	(ISO 8601, reproductible) Horaire de départ, departure_time, du stop_time auquel commence l'étape. La valeur de l'horaire de ce champ est conforme à ISO 8601, avec la chaîne de format suivante : YYYY-MM-DDThh:mm:ss±hh:mm Tous les horaires ci-dessous sont identiques, même s'ils utilisent différents fuseaux : À Londres, au Royaume-Uni : 2019-07-29T18:26:00+01:00 À New York, aux États-Unis : 2019-07-29T13:26:00-04:00 À Tokyo, au Japon : 2019-07-30T02:26:00+09:00 Important : Le fuseau horaire n'est pas nécessairement le même que celui de l'agence dans le flux. Il utilise le format UTC. Ce champ est formaté comme un tableau JSON.
arrival_time	(ISO 8601, reproductible) Heure d'arrivée, arrival_time au stop_time où le trajet se termine. La valeur de l'horaire de ce champ est conforme à ISO 8601, avec la chaîne de format suivante : YYYY-MM-DDThh:mm:ss±,hh:mm Tous les horaires ci-dessous sont identiques, même s'ils utilisent différents fuseaux : À Londres, au Royaume-Uni : 2019-07-29T18:46:00+01:00 À New York, aux États-Unis : 2019-07-29T13:46:00-04:00 À Tokyo, au Japon : 2019-07-30T02:46:00+09:00 Important : Le fuseau horaire n'est pas nécessairement le même que celui de l'agence dans le flux. Il utilise le format UTC. Ce champ est formaté comme un tableau JSON.

Exemples

Dans cet exemple, les étapes du parcours d'un passager sont les suivantes :

• À la date du service 20190716, l'ID de billetterie ti1 va de l'ID de billetterie de l'heure d'arrêt 11 à l'ID 12. Le passager monte à 14h et arrive à 14h50 (UTC).
• À la date du service 20190716, l'ID de billetterie ti2 va de l'ID de billetterie de l'heure d'arrêt 21 à l'ID 22. Le passager monte à 15h et arrive à 15h50 (UTC).

Dans cet exemple, web_url est https://examplepetstore.com.

Compte tenu de toutes ces informations, utilisez les valeurs suivantes pour les paramètres du flux pour ce trajet :

Nom du champ	Détails
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"]

Voici l'URI final après encodage :

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

Exemples de différentes valeurs ticketing_stop_id

Les arrêts peuvent avoir des ID différents pour la billetterie avec le champ ticketing_identifiers.txt. Les valeurs en gras se trouvent dans l'appel Web décrit après les fichiers.

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_url tdl1, https://examplepetstore.com/api/gtfs/web, https://examplepetstore.com/api/gtfs/android, https://examplepetstore.com/api/gtfs/ios

Si la requête est effectuée le 19/07/2019 et que les heures GTFS sont dans le fuseau horaire UTC+1, l'appel pour le Web est le suivant :

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

Important : Notez que les valeurs dans boarding_time et arrival_time, qui sont en UTC, ne suivent pas nécessairement le fuseau horaire GTFS (UTC+1), ce qui entraîne un décalage de la valeur HH:MM:SS.

Pratiques recommandées

Pour implémenter les extensions de billetterie Google Transports en commun, suivez ces recommandations :

Consignes
Dans la mesure du possible, partagez les liens profonds entre les agences ou itinéraires.	Dans le flux statique, chaque fois que plusieurs agences ou itinéraires ont les mêmes URL de liens profonds, elles doivent partager une seule valeur pour le champ ticketing_deep_link_id. Cela permet d'effectuer des transferts entre les agences ou les itinéraires. Remarque : Si ce n'est pas le cas, les passagers doivent acheter deux billets distincts en raison de valeurs différentes dans ticketing_deep_link_id.
Définissez des valeurs cohérentes pour ticketing_type.	La valeur ticketing_type d'un arrêt spécifique doit être cohérente pour toutes les lignes du fichier stop_times.txt. Remarque : Si la valeur ticketing_type est définie sur 1, la billetterie est désactivée pour tous les trajets passant par cet arrêt.
Mappez ticketing_stop_id pour les arrêts parents et enfants.	Mappez tous les arrêts principaux et enfants nécessitant une billetterie. Dans le fichier ticketing_identifiers.txt, les valeurs ticketing_stop_id ne se propagent pas entre un arrêt parent et ses enfants.
Mappez ticketing_stop_id pour chaque agence qui utilise le même arrêt dans le flux.	Dans le flux statique, si plusieurs agences qui activent la billetterie partagent le même arrêt, le mappage doit être présent pour chacune d'entre elles. Pour en savoir plus, consultez la section Définition des champs pour ticketing_identifiers.txt.
Utilisez Android App Links lorsqu'un lien profond vers une application Android est requis.	Si le partenaire souhaite ouvrir une application Android à partir d'un lien profond, configurez-le en tant qu'Android App Link. Remarque : Si le partenaire souhaite uniquement ouvrir un site Web mobile, utilisez directement l'URL du site Web.
Utilisez des liens universels iOS lorsqu'un lien profond vers une application iOS est requis.	Si le partenaire souhaite ouvrir une application iOS à partir d'un lien profond, configurez-le en tant que lien universel iOS.