Google Transit ticketing extensions

This page defines the subset of the GTFS-Ticketing specification, which is in the proposal stage during creation of this document. This page also includes several additional restrictions from Google.

Requirements

The field departure_time in stop_times.txt is necessary.

Additional Field Types

This section outlines the additional field types, as well as those with extensions from Google.

• URI: A fully qualified Uniform Resource Identifier (URI) that includes the scheme. Any special characters in the URI must use the correct escapes. For a description of how to create fully qualified URI values, see RFC 3986 Uniform Resource Identifier (URI): Generic Syntax.

File extensions or additions

File name	State	Defines
agency.txt	Extension	Adds agency.ticketing_deep_link_id
routes.txt	Extension	Adds routes.ticketing_deep_link_id
trips.txt	Extension	Adds trips.trip_ticketing_id, trips.ticketing_type
stop_times.txt	Extension	Adds stop_times.ticketing_type
ticketing_identifiers.txt	Addition
ticketing_deep_links.txt	Addition

Tables Definitions

agency.txt (file extended)

Field name	Presence	Details
ticketing_deep_link_id	Optional	(ID from ticketing_deep_links.txt) Defines the deep link to use for this agency. Can be overwritten in routes.txt.

routes.txt (file extended)

Field name	Presence	Details
ticketing_deep_link_id	Optional	(ID from ticketing_deep_links.txt) Defines the deep link to use for this route. If present, overwrites the one in agency.txt.

trips.txt (file extended)

Field name	Presence	Details
ticketing_trip_id	Optional	(ID) Identifier to pass in the deep link. Doesn’t have to be unique. Fallbacks on the trip_id.
ticketing_type	Optional	(Enum) Define if the ticketing through deep link is available for this trip: 0 or empty: assumed to be: Available if a ticketing_deep_link_id is defined on the route or agency. Unavailable otherwise. 1: Unavailable.

stop_times.txt (file extended)

Field name	Presence	Details
ticketing_type	Optional	(Enum) Define if the ticketing through deep link is available for this stop_time. If defined, override the value set in trip.ticketing_type. Empty: As defined by trip.ticketing_type. 0: assumed to be: Available if a ticketing_deep_link_id is defined on the route or agency. Unavailable otherwise. Important: For a particular stop_id, if any of its stop_times has ticketing_type=1, then all of its other stop_times must also have ticketing_type=1.

ticketing_identifiers.txt (file added)

The most common case for ticketing is that every stop has an identifier to process billing. Different agencies might use the same identifier for any given stop. When multiple agencies serve the same stop, repeat this mapping for each agency.

Field name	Presence	Details
ticketing_stop_id	Required	(ID) Define a default ticketing ID for this stop for this agency.
stop_id	Required	(ID from stops.txt) The stop for which the default ticketing_stop_id is defined.
agency_id	Required	(ID from agency.txt) The agency of the stop for which the default ticketing_stop_id is defined.

ticketing_deep_links.txt (file added)

Field name	Presence	Details
ticketing_deep_link_id	Required	(ID) Define an ID for the deep link.
web_url	Optional	(URL) The URL to visit for deep linking. Translations can be supplied via translations.txt to send riders to locale-specific URLs.
android_intent_uri	Optional	(URI) The URI to pass to a native Android app with an android.intent.action.VIEW intent. If empty, it means no deep-linking to a native Android app. Important: There’s no support for URL translation for this field, so language detection must be done by the receiving website/app. For more information about deep links on Android, see Create Deep Links to App Content. Recommendation: Use Android App Links, which are both more secure and have a better fallback behavior, when the rider doesn’t have the native Android app on their device. This field isn't translatable via translations.txt.
ios_universal_link_url	Optional	(URL) The universal link URL to invoke on iOS. Important: There’s no support for URL translation for this field, so language detection must be done by the receiving website/app. If empty, deep linking doesn't display on iOS. For more information, see Universal Links on iOS. This field isn't translatable via translations.txt.

Best Practice: When multiple agencies/routes share the same deep link URLs, we strongly recommend to only define one deep link and link all those agencies/routes to the same deep link.

Field Placeholders in the API call

Google calls the previous URLs with the following parameters:

Field name	Presence	Details
service_date	Required	(Date, Repeatable) Service day of the trip. This field formats as a JSON array.
ticketing_trip_id	Required	(ID from trips.txt, Repeatable) Identifier of the trip. This field formats as a JSON array.
from_ticketing_stop_time_id	Required	(Repeatable) Identifier of the stop_time at which the leg starts. For a particular stop time, the value is: The ticketing_stop_id defined in ticketing_identifiers.txt for the agency_id and the stop_id of the stop_time. Important: This only uses the ticketing_identifiers for the stop itself. Even if the stop has a parent stop, we ignore the ticketing_identifiers of the parent stop. Else, it falls back on the stop_sequence. This field formats as a JSON array.
to_ticketing_stop_time_id	Required	(Repeatable) Identifier of the stop_time at which the leg ends. See from_ticketing_stop_time_id for an explanation on the derivation of the value. This field formats as a JSON array.
boarding_time	Required	(ISO 8601, Repeatable) Time of departure (departure_time) of the stop_time at which the leg starts. The time value of this field conforms to ISO 8601, with the following format string: YYYY-MM-DDThh:mm:ss±hh:mm All the times below are the same, in different time-zones: In London, UK: 2019-07-29T18:26:00+01:00 In NYC, US-NY: 2019-07-29T13:26:00-04:00 In Tokyo, JP: 2019-07-30T02:26:00+09:00 Important: The timezone isn't necessarily the same timezone for the agency in the feed. The timezone is in UTC. This field formats as a JSON array.

Examples

If the legs are:

• On service date 20190716, trip ticketing id ti1 from stop time ticketing id 11 to stop time ticketing id 12, boarding at 2 PM UTC
• On service date 20190716, trip ticketing id ti2 from stop time ticketing id 21 to stop time ticketing id 22, boarding at 3 PM UTC

And the web_url is: http://myawesomebookingwebsite.com

The values of the parameters are:

Field name	Details
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"]

The final URI (after encoding) is:

http://myawesomebookingwebsite.com?service_date=%5B%2220190716%22,%22%2019071622%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

Examples of different ticketing_stop_id values

Stops can have different IDs for the purposes of ticketing with the ticketing_identifiers.txt field. Values in bold are those found in the web call described after the files.

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

The call for the web, if the request is made on 2019-07-19 and the GTFS times are in timezone UTC+1, is:

http://www.thetrainline.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-19T07:59:00%2B00:00%22%5D

Important: Note that the value inside boarding_time (which is UTC) doesn’t necessarily follow the timezone in GTFS (UTC+1), which causes a shift in the HH:MM:SS value.