本页面定义了一部分 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 |
可选 |
(来自 |
routes.txt
(文件已扩展)
字段名称 | 在家/外出状态 | 具体说明 |
---|---|---|
ticketing_deep_link_id |
可选 | (来自 ticketing_deep_links.txt 的 ID)定义要用于此路线的深层链接。如果存在,则覆盖 agency.txt 中的字段。 |
trips.txt
(文件已扩展)
字段名称 | 在家/外出状态 | 具体说明 |
---|---|---|
ticketing_trip_id |
可选 |
(ID) 要在深层链接中传递的标识符。无需具有唯一性。 如果 |
ticketing_type |
可选 |
(枚举)定义此行程是否可通过深层链接进行票务预订:
|
stop_times.txt
(文件已扩展)
字段名称 | 在家/外出状态 | 具体说明 |
---|---|---|
ticketing_type |
可选 |
(枚举)定义此经停时间是否可通过深层链接进行票务处理。如果您定义
|
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 |
可选 |
(网址)要访问的深层链接网址。 此字段无法通过 |
android_intent_uri |
可选 |
(URI) 通过 如果为空,则表示您无法深层链接到原生 Android 应用。 如需详细了解 Android 上的深层链接,请参阅创建指向应用内容的深层链接。 此字段无法通过 |
ios_universal_link_url |
可选 |
(网址)要在 iOS 上调用的通用链接网址。 如果为空,深层链接不会在 iOS 上显示。 如需了解详情,请参阅 iOS 上的通用链接。 此字段无法通过 |
API 调用中的字段占位符
Google 使用以下参数调用 ticketing_deep_links.txt
中定义的网址:
字段名称 | 具体说明 |
---|---|
service_date |
(日期,可重复)行程的服务日。 此字段用于指定行程从第一个经停点出发的日期。 此字段的格式设置为 JSON 数组。 |
ticketing_trip_id |
(来自 此字段的格式设置为 JSON 数组。 |
from_ticketing_stop_time_id |
(可重复)路程起点 特定停止时间的值如下:
此字段的格式设置为 JSON 数组。 |
|
(可重复)路程终点的 有关此值的派生的说明,请参阅 此字段的格式设置为 JSON 数组。 |
boarding_time |
(ISO 8601,可重复)路程起点的 此字段用于指定乘客上车的实际日期和时间。 此字段的时间值符合 ISO 8601 和以下字符串格式:
以下所有时间都相同,只是位于不同的时区:
此字段的格式设置为 JSON 数组。 |
arrival_time |
(ISO 8601,可重复)到达时间,路程结束的 stop_time 的 arrival_time。 此字段的时间值符合 ISO 8601 和以下字符串格式:
以下所有时间都相同,只是位于不同的时区:
此字段的格式设置为 JSON 数组。 |
示例
在此示例中,以下是乘客旅程的路程:
- 在服务日期
20190716
,行程票务 IDti1
从停止时间票务 ID11
开始,从停止时间票务 ID12
开始。乘客在世界协调时间 (UTC) 下午 2:00 上车,并于下午 2:50 到达(世界协调时间)。 - 在服务日期
20190716
,行程票务 IDti2
从停止时间票务 ID21
开始,从停止时间票务 ID22
开始。乘客在世界协调时间 (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 |
---|
|
routes.txt |
---|
|
trips.txt |
---|
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 |
---|
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 |
---|
si1、agency1、4924 si2、agency1、4676 |
ticketing_deep_links.txt |
---|
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
推荐做法
请按照以下建议实现 Google 公交票卡扩展程序:
指南 | |
---|---|
尽可能在代理机构或路线之间共享深层链接。 |
在静态 Feed 中,如果多个代理机构或路由具有相同的深层链接网址,它们必须共用 |
为 ticketing_type 设置一致的值。 |
特定经停点的 |
映射父站和子站的 ticketing_stop_id 。 |
为所有需要票务的父级和子级停靠站执行映射。在 ticketing_identifiers.txt 文件中,ticketing_stop_id 值不会在父站及其子站之间传播。 |
为在 Feed 中使用同一经停点的每个代理机构映射 ticketing_stop_id 。 |
在静态 Feed 中,如果多个启用票务的代理机构共用同一个经停点,则每个代理机构都必须具有映射。 如需了解详情,请参阅 |
如果需要指向 Android 应用的深层链接,请使用 Android App Links。 |
如果合作伙伴想要通过深层链接打开 Android 应用,请将深层链接设置为 Android 应用链接。 |
如果需要指向 iOS 应用的深层链接,请使用 iOS 通用链接。 | 如果合作伙伴想要通过深层链接打开 iOS 应用,请将深层链接设置为 iOS 通用链接。 |