Google 公交票务扩展程序

本页定义了 GTFS 票务规范的一部分，该规范在本文档创建期间处于提案阶段。此页面还包含 Google 的其他几项限制。

要求

stop_times.txt 中的 departure_time 字段是必需的。

其他字段类型

本部分概述了其他字段类型以及 Google 提供的扩展字段。某些字段要求值采用 URI 格式。

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

文件扩展名或附加内容

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

状态为添加的文本文件是 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，请在 agency.txt 文件中为所有代理机构的 ticketing_deep_link_id 字段设置相同的值。

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.intent.action.VIEW intent 传递给原生 Android 应用的 URI。 如果为空，则表示您无法深层链接到原生 Android 应用。 重要提示：此字段不支持网址翻译，因此接收网站或应用必须执行语言检测。 如需详细了解 Android 上的深层链接，请参阅创建指向应用内容的深层链接。 建议：使用 Android 应用链接。这种方式更安全，并且当乘客设备上没有原生 Android 应用时，具有更好的后备行为。 此字段无法通过 translations.txt 进行翻译。
ios_universal_link_url	可选	（网址）要在 iOS 上调用的通用链接网址。 重要提示：此字段不支持网址翻译，因此接收网站或应用必须执行语言检测。 如果为空，则深层链接不会在 iOS 上显示。 如需了解详情，请参阅 iOS 上的通用链接。 此字段无法通过 translations.txt 进行翻译。

注意：如果 Feed 中多个代理机构或路线共用相同的深层链接网址，我们强烈建议您仅定义一个深层链接，并将所有这些代理机构或路线都关联到该深层链接。如需了解详情，请参阅建议的做法部分。

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 中为 agency_id 和 stop_time 的 stop_id 定义的 ticketing_stop_id。 重要提示：这仅将 ticketing_identifiers 用于相应经停点本身。即使相应经停点有父级经停点，我们也会忽略父级经停点的 ticketing_identifiers。 否则，它会回退到 stop_sequence。 此字段的格式为 JSON 数组。
to_ticketing_stop_time_id	（可重复）相应路段结束处的 stop_time 的标识符。 如需了解该值的派生方式，请参阅 from_ticketing_stop_time_id。 此字段的格式为 JSON 数组。
boarding_time	（ISO 8601，可重复）相应航段的起始时间 stop_time 的出发时间 departure_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 为 11，结束时间票券 ID 为 12。乘客于世界协调时间下午 2:00 上车，并于世界协调时间下午 2:50 到达。
• 在服务日期 20190716 中，行程票券 ID ti2 的起始时间票券 ID 为 21，结束时间票券 ID 为 22。乘客于世界协调时间下午 3:00 上车，并于世界协调时间下午 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 值的示例

为了使用 ticketing_identifiers.txt 字段进行票务处理，相应经停点可以具有不同的 ID。粗体值是文件后面所述的网络调用中找到的值。

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

如果请求是在 2019-07-19 发出，并且 GTFS 时间采用 UTC+1 时区，则 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

重要提示：请注意，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 值不会在父级经停点及其子项之间传播。
为 Feed 中使用相同经停点的每个代理机构映射 ticketing_stop_id。	在静态 Feed 中，如果启用了票务功能的多个代理机构共用同一经停点，则必须为每个代理机构提供映射。 如需了解详情，请参阅 ticketing_identifiers.txt 的字段定义部分。
如需使用指向 Android 应用的深层链接，请使用 Android 应用链接。	如果合作伙伴希望通过深层链接打开 Android 应用，请将深层链接设置为 Android App Link。 注意：如果合作伙伴只想打开适用于移动设备的网站，请直接使用网站网址。
如需使用指向 iOS 应用的深层链接，请使用 iOS 通用链接。	如果合作伙伴希望通过深层链接打开 iOS 应用，请将深层链接设置为 iOS 通用链接。