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.

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.

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.

For more information about deep links on Android, see Create Deep Links to App Content.

This field isn't translatable via translations.txt.

ios_universal_link_url Optional

(URL) The universal link URL to invoke on iOS.

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.

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

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