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.

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.
  • 1 : non disponible.

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

Pour en savoir plus sur les liens profonds sur Android, consultez Créer des liens profonds vers le contenu d'une application.

Ce champ ne peut pas être traduit via translations.txt.
ios_universal_link_url Facultatif

(URL) URL du lien universel à appeler sur iOS.

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.

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.

  • 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

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

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

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