Google 公交票务扩展

本页面定义了一部分 GTFS-Ticketing 规范，该规范处于本文档创建期间处于提案阶段。本页还需遵守 Google 提供的一些额外限制。

要求

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

其他字段类型

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

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

文件扩展名或添加项

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

状态为“Addition”的文本文件是 Google Transit Ticketing Extensions 推出的新文件。您需要根据下表后提供的字段定义创建这些文件。请务必在 Feed 中添加这些文件。

文件名	状态	定义
agency.txt	扩展程序	添加 agency.ticketing_deep_link_id。
routes.txt	扩展程序	添加 routes.ticketing_deep_link_id。
trips.txt	扩展程序	添加 trips.trip_ticketing_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 App Links，这两种链接更安全，而且在乘客设备上未安装原生 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，可重复）到达时间，路程结束的 stop_time 的 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 开始。乘客在世界协调时间 (UTC) 下午 2:00 上车，并于下午 2:50 到达（世界协调时间）。
• 在服务日期 20190716，行程票务 ID ti2 从停止时间票务 ID 21 开始，从停止时间票务 ID 22 开始。乘客在世界协调时间 (UTC) 下午 3:00 登机，并于下午 3:50 抵达世界协调时间 (UTC)。

在此示例中，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，“巴黎里昂火车站” 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 年 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 值不会在父站及其子站之间传播。
为在 Feed 中使用同一经停点的每个代理机构映射 ticketing_stop_id。	在静态 Feed 中，如果多个启用票务的代理机构共用同一个经停点，则每个代理机构都必须具有映射。 如需了解详情，请参阅 ticketing_identifiers.txt 的字段定义部分。
如果需要指向 Android 应用的深层链接，请使用 Android App Links。	如果合作伙伴想要通过深层链接打开 Android 应用，请将深层链接设置为 Android 应用链接。 注意：如果合作伙伴只想打开一个支持移动设备的网站，请直接使用网站网址。
如果需要指向 iOS 应用的深层链接，请使用 iOS 通用链接。	如果合作伙伴想要通过深层链接打开 iOS 应用，请将深层链接设置为 iOS 通用链接。