Google 公交票务扩展

本页面定义了处于提案阶段的 GTFS-Ticketing 规范的子集 您创建此文档时遇到的所有问题此页面还包含 Google。

要求

必须提供 stop_times.txt 中的 departure_time 字段。

其他字段类型

本部分概述了其他字段类型以及带有 Google 扩展功能的字段类型。部分 字段需要 URI 形式的值。

• URI：包含架构的完全限定统一资源标识符 (URI)。不限 URI 中的特殊字符必须使用正确的转义。如需了解如何创建 完全限定的 URI 值，请参阅 RFC 3986 统一资源标识符 (URI)：通用语法。

文件扩展名或附加内容

状态为 Extension 的文本文件是已存在且您需要 扩展。您必须添加我们在下表中定义的新字段。

状态为 Addition 的文本文件是由 Google 公交引入的新文件 工单扩展程序。您在创建这些文件时需要遵循 下表后面给出了字段定义。请务必 将这些文件添加到您的 Feed 中

文件名	州	定义
agency.txt	扩展程序	添加了 agency.ticketing_deep_link_id。
routes.txt	扩展程序	添加了 routes.ticketing_deep_link_id。
trips.txt	扩展程序	添加 trips.ticketing_trip_id 和 trips.ticketing_type。
stop_times.txt	扩展程序	添加了 stop_times.ticketing_type。
ticketing_identifiers.txt	加法	新文件。如需了解详情，请参阅字段定义。
ticketing_deep_links.txt	加法	新文件。如需了解详情，请参阅字段定义。

字段定义

agency.txt（扩展了文件）

字段名称	在家/外出状态	详细信息
ticketing_deep_link_id	可选	（来自 ticketing_deep_links.txt 的 ID）定义要用于此项的深层链接 代理机构。可在 routes.txt 中覆盖。 注意：如需将票务功能应用于整个静态 Feed，请设置相同的 值代表 ticketing_deep_link_id 字段中所有代理机构 agency.txt 文件。

routes.txt（扩展了文件）

字段名称	在家/外出状态	详细信息
ticketing_deep_link_id	可选	（来自 ticketing_deep_links.txt 的 ID）定义要用于此项的深层链接 。如果存在，则覆盖 agency.txt 中的字段。

trips.txt（扩展了文件）

字段名称	在家/外出状态	详细信息
ticketing_trip_id	可选	(ID) 要在深层链接中传递的标识符。不一定是唯一的。 如果 ticketing_trip_id 为空，系统会使用 trip_id。
ticketing_type	可选	（枚举）定义此行程是否可通过深层链接购票： 0 或为空： 如果您为路线或交通机构定义了 ticketing_deep_link_id，则该字段为 可用。 在其他情况下无法使用。 1：不可用。

stop_times.txt（扩展了文件）

字段名称	在家/外出状态	详细信息
ticketing_type	可选	（枚举）定义此停止时间是否可以通过深层链接票务。如果 您定义了 stop_times.ticketing_type，它会替换在 trip.ticketing_type。 空：使用 trip.ticketing_type 中的值。 0： 如果您为路线或交通机构定义了 ticketing_deep_link_id，则该字段为 可用。 在其他情况下无法使用。 1：不可用。 。 重要提示：对于特定的 stop_id，如果其任何 stop_times 拥有 ticketing_type=1，以及它的所有其他 stop_times 还必须具有 ticketing_type=1。

ticketing_identifiers.txt（已添加文件）

最常见的票务用例是每个经停点都有一个标识符，用于处理结算。 对于任何给定站点，不同的机构可能使用相同的标识符。当多个代理机构 对每个代理商重复此映射。

字段名称	在家/外出状态	详细信息
ticketing_stop_id	必需	(ID) 定义此代理机构的此经停点的默认票务 ID。
stop_id	必需	（来自 stops.txt 的 ID）默认的停车点 已定义 ticketing_stop_id。
agency_id	必需	（来自 agency.txt 的 ID）默认停靠站的代理机构 已定义 ticketing_stop_id。

ticketing_deep_links.txt（已添加文件）

字段名称	在家/外出状态	详细信息
ticketing_deep_link_id	必需	(ID) 定义深层链接的 ID。
web_url	可选	（网址）深层链接要访问的网址。 此字段无法通过 translations.txt 进行翻译。 重要提示：不支持网址转换 字段，因此语言检测必须由接收方网站或应用完成。
android_intent_uri	可选	(URI) 要传递给原生 Android 应用的 URI，该 URI 带有 android.intent.action.VIEW intent。 如果为空，则表示您无法深层链接到原生 Android 应用。 重要提示：不支持网址转换 字段，因此语言检测必须由接收方网站或应用完成。 如需详细了解 Android 上的深层链接，请参阅创建指向 应用内容。 建议：使用 Android App Links，后者更加安全 并在乘客未安装原生 Android 应用时提供更好的后备行为 。 此字段无法通过 translations.txt 进行翻译。
ios_universal_link_url	可选	(网址) 要在 iOS 上调用的通用链接网址。 重要提示：不支持网址转换 字段，因此语言检测必须由接收方网站或应用完成。 如果为空，深层链接不会在 iOS 上显示。 如需了解详情，请参阅 iOS 上的通用链接。 此字段无法通过 translations.txt 进行翻译。

注意：如果多个代理机构或航线在 因此，我们强烈建议您仅定义一个深层链接并将所有这些链接 代理机构或路由指向同一深层链接。有关详情，请参阅 推荐做法部分。

API 调用中的字段占位符

Google 使用以下代码调用 ticketing_deep_links.txt 中定义的网址 参数：

字段名称	详细信息
service_date	（日期，可重复）行程的服务日期。 使用此字段作为行程从其第一站出发的日期。 此字段采用 JSON 数组的格式。
ticketing_trip_id	（来自 trips.txt 的 ID，可重复）行程的标识符。 此字段采用 JSON 数组的格式。
from_ticketing_stop_time_id	（可重复）路程起点 stop_time 的标识符。 对于特定停止时间，此值如下： 在 ticketing_identifiers.txt 中定义的 ticketing_stop_id 的 agency_id 和 stop_id stop_time。 重要提示：这仅会使用 ticketing_identifiers。即使经停点有父级 因此会忽略父级停靠站的 ticketing_identifiers。 否则，它会回退到 stop_sequence。 此字段采用 JSON 数组的格式。
to_ticketing_stop_time_id	（可重复）路程结束处的 stop_time 的标识符。 有关推导该值的说明，请参阅 from_ticketing_stop_time_id。 此字段采用 JSON 数组的格式。
boarding_time	（ISO 8601，可重复）出发时间，departure_time， 路程起点的 stop_time。 此字段可用于显示乘客上车的实际日期和时间。 此字段的时间值符合 ISO 8601 以下字符串格式： YYYY-MM-DDThh:mm:ss±hh:mm 以下所有时间都是相同的，只是时区不同： 英国伦敦：2019-07-29T18:26:00+01:00 纽约州（美国）- 纽约州：2019-07-29T13:26:00-04:00 日本东京：2019-07-30T02:26:00+09:00 。 重要提示：时区不一定相同 Feed 中代理机构的时区。时区采用世界协调时间 (UTC)。 此字段采用 JSON 数组的格式。
arrival_time	（ISO 8601，可重复）到达时间，目的地到达时间的 arrival_time 结束。 此字段的时间值符合 ISO 8601，并采用以下字符串格式： YYYY-MM-DDThh:mm:ss±,hh:mm 以下所有时间都是相同的，只是时区不同： 英国伦敦：2019-07-29T18:46:00+01:00 纽约、美国-纽约：2019-07-29T13:46:00-04:00 日本东京：2019-07-30T02:46:00+09:00 。 重要提示：代理机构的时区不一定与 Feed。时区采用世界协调时间 (UTC)。 此字段采用 JSON 数组的格式。

示例

在此示例中，以下是乘客行程的路程：

• 在服务日期 20190716，行程票券 ID ti1 从停靠站开始 用于停止时间工单 ID 12 的时间工单 ID 11。乘客 在世界协调时间 (UTC) 下午 2:00 登机，在世界协调时间 (UTC) 下午 2:50 抵达。
• 在服务日期 20190716，行程票券 ID ti2 从停靠站开始 时间票券 ID 21，用于停止时间票券 ID 22。乘客 在世界协调时间 (UTC) 下午 3:00 登机，在世界协调时间 (UTC) 下午 3:50 到达。

在此示例中，web_url 为 https://examplepetstore.com。

了解所有这些信息后，请为此 Feed 的 参数使用以下值 行程：

字段名称	详细信息
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"]

以下是编码后的最终 URI：

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

不同方法的示例 ticketing_stop_id 个值

站点可以具有不同的 ID，以便使用 ticketing_identifiers.txt 字段。以粗体显示的值是在网络调用中找到的值 文件后面描述的内容

stop.txt
stop_id，stop_name si1，“巴黎里昂火车站” 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,每天,ri1,"TGV INOUI 6603",FR_SNCF_6603 ti2、每天、ri1、"TGV INOUI 6681"、FR_SNCF_6681 ti3、每天、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

如果请求是在 2019 年 7 月 19 日发出的，且 GTFS 时间采用的是 UTC+1 时区，则 以下是对网络的调用：

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

重要提示：请注意，boarding_time 中的值 和 arrival_time（采用 UTC 格式）不一定遵循 GTFS 中的时区 (UTC+1)，这会导致 HH:MM:SS 值发生变化。

推荐做法

请按照以下建议实施 Google 公交票务扩展程序：

指南
尽可能在公交公司或路线之间共享深层链接。	在静态 Feed 中，每当多个代理机构或路线具有相同的深层链接网址时， 它们的 ticketing_deep_link_id 字段必须共用一个值。这个 支持在代理机构或路线之间转移。 注意：否则，乘客必须购买两张分段机票，因为 ticketing_deep_link_id 中的不同值。
为 ticketing_type 设置一致的值。	特定经停点的 ticketing_type 值必须在所有 stop_times.txt 文件中的行。 注意：ticketing_type 值为 1 为使用指定经停点的所有行程停用票务功能。
为父站和子站映射 ticketing_stop_id。	为需要票务的所有父站和子站执行映射。在 ticketing_identifiers.txt 文件，ticketing_stop_id 值 在父站及其子站之间传播。
为在以下位置使用相同经停点的每个代理机构映射ticketing_stop_id： Feed。	在静态 Feed 中，如果启用票务功能的多个代理机构共用同一个经停点， 每个代理机构都必须有相应的映射 如需了解详情，请参阅字段定义部分 价格为 ticketing_identifiers.txt。
当需要指向 Android 应用的深层链接时，使用 Android App Links。	如果合作伙伴希望通过深层链接打开 Android 应用，请将深层链接设置为 一个 Android 应用链接 注意：如果合作伙伴只想打开一个支持移动设备的网站， 直接使用网站网址。
当需要指向 iOS 应用的深层链接时，请使用 iOS 通用链接。	如果合作伙伴希望通过深层链接打开 iOS 应用，请将深层链接设置为 iOS 通用链接。