Google Transit ticketing extensions

This page defines a subset of the GTFS-Ticketing specification, which is in the proposal stage during the 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 and those with extensions from Google. Some fields require values in the form of a URI.

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

The text files with the state Extension are files that already exist and that you need to extend. You must add the new fields that we define in the following table.

The text files with the state Addition are new files introduced by the Google Transit Ticketing Extensions. You need to create these files in accordance with the Field definitions given after the following table. Be sure to include these files in your feed.

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.ticketing_trip_id` and `trips.ticketing_type`.
`stop_times.txt`	Extension	Adds `stop_times.ticketing_type`.
`ticketing_identifiers.txt`	Addition	New file. For more details, see Field definitions.
`ticketing_deep_links.txt`	Addition	New file. For more details, see Field definitions.

Field 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`. Note: To apply ticketing to the whole static feed, set the same value in the `ticketing_deep_link_id` field for all agencies in the `agency.txt` file.

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 field in `agency.txt`.

trips.txt (file extended)

Field name Presence Details

Field name	Presence	Details
`ticketing_trip_id`	Optional	(ID) Identifier to pass in the deep link. Doesn't have to be unique. If `ticketing_trip_id` is empty, the system uses the value of `trip_id` instead.
`ticketing_type`	Optional	(Enum) Define whether ticketing through a deep link is available for this trip: `0` or empty: If you define a `ticketing_deep_link_id` for the route or agency, this is available. Unavailable otherwise. `1`: Unavailable.

ticketing_trip_id

Optional

(ID) Identifier to pass in the deep link. Doesn't have to be unique.

If ticketing_trip_id is empty, the system uses the value of trip_id instead.

ticketing_type

Optional

(Enum) Define whether ticketing through a deep link is available for this trip:

0 or empty:

If you define a ticketing_deep_link_id for the route or agency, this is available.
Unavailable otherwise.

1: Unavailable.

stop_times.txt (file extended)

Field name Presence Details

Field name	Presence	Details
`ticketing_type`	Optional	(Enum) Defines whether ticketing through a deep link is available for this stop time. If you define `stop_times.ticketing_type`, this overrides the value set in `trip.ticketing_type`. Empty: Uses the value from `trip.ticketing_type`. `0`: If you define a `ticketing_deep_link_id` for the route or agency, this is available. Unavailable otherwise. `1`: Unavailable. 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_type

Optional

(Enum) Defines whether ticketing through a deep link is available for this stop time. If you define stop_times.ticketing_type, this overrides the value set in trip.ticketing_type.

Empty: Uses the value from trip.ticketing_type.
0:

If you define a ticketing_deep_link_id for the route or agency, this is available.
Unavailable otherwise.

1: Unavailable.

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) Defines 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) Defines an ID for the deep link.
`web_url`	Optional	(URL) The URL to visit for deep linking. This field isn't translatable through `translations.txt`. Important: There's no support for URL translation for this field, so language detection must be done by the receiving website or app.
`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 you can't deep link 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 or 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 passenger doesn't have the native Android app on their device. This field isn't translatable through `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 or app. If empty, deep linking doesn't display on iOS. For more information, see Universal Links on iOS. This field isn't translatable through `translations.txt`.

Field placeholders in the API call

Google calls the URLs defined in ticketing_deep_links.txt with the following parameters:

Field name	Details
`service_date`	(Date, repeatable) Service day of the trip. Use this field for the date when the trip departs from its first stop. This field formats as a JSON array.
`ticketing_trip_id`	(ID from `trips.txt`, repeatable) Identifier of the trip. This field formats as a JSON array.
`from_ticketing_stop_time_id`	(Repeatable) Identifier of the `stop_time` at which the leg starts. For a particular stop time, the value is the following: 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`	(Repeatable) Identifier of the `stop_time` at which the leg ends. For an explanation on the derivation of the value, see `from_ticketing_stop_time_id`. This field formats as a JSON array.
`boarding_time`	(ISO 8601, repeatable) Time of departure, `departure_time`, of the `stop_time` at which the leg starts. Use this field for the actual date and time when the passenger boards the vehicle. The time value of this field conforms to ISO 8601 with the following string format: `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 time zone isn't necessarily the same time zone for the agency in the feed. The time zone is in UTC. This field formats as a JSON array.
`arrival_time`	(ISO 8601, repeatable) Time of arrival, arrival_time at the stop_time at which the leg ends. The time value of this field conforms to ISO 8601 with the following string format: `YYYY-MM-DDThh:mm:ss±,hh:mm` All the times below are the same, in different time zones: In London, UK: 2019-07-29T18:46:00+01:00 In NYC, US-NY: 2019-07-29T13:46:00-04:00 In Tokyo, JP: 2019-07-30T02:46:00+09:00 Important: The time zone isn't necessarily the same time zone for the agency in the feed. The time zone is in UTC. This field formats as a JSON array.

Examples

In this example, the following are the legs of a passenger's journey:

On service date 20190716, trip ticketing ID ti1 begins from stop time ticketing ID 11 to stop time ticketing ID 12. The passenger boards at 2:00 PM UTC and arrives at 2:50 PM UTC.
On service date 20190716, trip ticketing ID ti2 begins from stop time ticketing ID 21 to stop time ticketing ID 22. The passenger boards at 3:00 PM UTC and arrives at 3:50 PM UTC.

For this example, the web_url is https://examplepetstore.com.

Given all of this information, use the following values for the parameters of the feed for this trip:

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"]`
`arrival_time`	`["2019-07-16T14:50:00+00:00"`, `"2019-07-16T15:50:00+00:00"]`

The following is the final URI after encoding:


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

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"

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`

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

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

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

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

If the request is made on 2019-07-19 and the GTFS times are in time zone UTC+1, then the following is the call for the 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

Important: Note that the values inside boarding_time and arrival_time, which are in UTC, don't necessarily follow the time zone in GTFS (UTC+1), which causes a shift in the HH:MM:SS value.

Recommended practices

Follow these recommendations to implement Google Transit ticketing extensions:

Guidelines
Share deep links between agencies or routes whenever possible.	In the static feed, whenever multiple agencies or routes have the same deep link URLs, they must share a single value for the `ticketing_deep_link_id` field. This enables transfers between agencies or routes. Note: If not, passengers must buy two separate tickets due to different values in `ticketing_deep_link_id`.
Set consistent values for `ticketing_type`.	The `ticketing_type` value for a particular stop must be consistent across all the rows in the `stop_times.txt` file. Note: A `ticketing_type` value of `1` disables ticketing for all trips that use that given stop.
Map `ticketing_stop_id` for both parent and child stops.	Perform the mapping for all the parent and child stops that require ticketing. In the `ticketing_identifiers.txt` file, the `ticketing_stop_id` values don't propagate between a parent stop and its children.
Map `ticketing_stop_id` for each agency that uses the same stop in the feed.	In the static feed, if multiple agencies that enable ticketing share the same stop, the mapping must be present for each of the agencies. For more details, refer to the Field definitions section for `ticketing_identifiers.txt`.
Use Android App Links when a deep link to an Android app is required.	If the partner wants to open up an Android app from a deep link, set up the deep link as an Android App Link. Note: If the partner only wants to open a mobile-enabled website, use the website URL directly.
Use iOS Universal Links when a deep link to an iOS app is required.	If the partner wants to open up an iOS app from a deep link, set up the deep link as an iOS Universal Link.

Google Transit ticketing extensions

Requirements

Additional field types

File extensions or additions

Field definitions

Field placeholders in the API call

Examples

Examples of different ticketing_stop_id values

Recommended practices

Examples of different `ticketing_stop_id` values