在继续本部分之前,请先验证您为其构建 Feed 的受支持的微移动系统(如果您尚未这样做)。
在以下部分中,每个头文件都采用以下格式:Required|Optional|Conditionally required: Feed name (System supported)
。支持以下系统:
- 基座系统
- 无底座系统
- 基座和无基座系统
为了成功与 Google 集成,请仅提供 Feed 描述的系统所需的文件,并指定相关部分中包含的必填字段。如需查看有条件的必填字段,请参阅该字段的说明以获取相关指导。您还可以指定可选字段,以添加信息并提供更好的用户体验。
微型 Feed 的必需标题
微移动 Feed 是指包含停靠式或无基站微型结构化数据的 Feed(如本文中所定义)。
所有 Feed 都必须始终在下表的 JSON 对象顶层指定下表包含的字段(统称为通用 GBFS 标头)。
字段名称 | 类型 | 要求 | 说明 |
---|---|---|---|
last_updated |
时间戳 | 必需 | POSIX 时间戳,用于指定自世界协调时间 (UTC) 1970 年 1 月 1 日 00:00:00 以来的秒数。 设置为 Feed 数据上次更新的时间。 |
ttl |
非负整数 | 必需 | 一个非负整数,表示更新 Feed 前的剩余秒数。 如果必须以恒定的速率更新数据,请将此值设置为 |
data |
JSON | 必需 | 包含单个 Feed 的数据字段的 JSON。 |
例如,指定通用 GBFS 标头的汇总 free_bike_status.json
Feed 可能如下所示:
{
"ttl": 30,
"last_updated": 1576123774,
"data": {
"bikes": [ ... ] // GBFS free bike status objects.
}
}
必需:system_information.json(基座和无基座系统)
请根据需要参阅 GBFS 规范。
此 Feed 提供了关于系统运算符的详细信息。
字段名称 | 类型 | 要求 | 说明 |
---|---|---|---|
system_id |
ID | 必需 | 车辆共享系统的全局唯一标识符。此值应在系统的生命周期内保持不变。车辆运营的每个不同的系统或地理区域都应有自己的 system_id。系统 ID 应可识别为属于特定系统(而非随机字符串),例如 bcycle_austin 或 Biketown_pdx。 |
name |
字符串 | 必需 | 系统的名称,会向客户显示。 |
rental_apps |
对象 | 必需 | 一个 JSON 对象,分别在对应字段中包含 Android 和 iOS 版租借应用的信息。 |
rental_apps.android |
对象 | Conditionally required |
在 store_uri 和 discovery_uri 字段中包含 Android 平台的租借应用下载和应用发现信息。如果系统提供程序有 Android 租借应用,则必须填写此字段。
|
rental_apps.android.store_uri |
URI | 必需 | 可从中下载 Android 版租借应用的 URI。这通常是应用商店(如 Google Play)的 URI。如果 URI 指向 Google Play 等应用商店,我们建议该 URI 遵循 Android 最佳做法,以便查看应用可以直接打开原生应用商店应用(而非网站)。 |
rental_apps.android.discovery_uri |
URI | 必需 | 采用 your_custom_scheme://your/path/here 格式的 URI。PackageManager.queryIntentActivities() 可以使用该 URI 发现设备上是否安装了租借的 Android 应用。
|
rental_apps.ios |
对象 | Conditionally required | 在 store_uri 和 discovery_uri 字段中包含 iOS 平台的租借应用下载和应用发现信息。如果系统提供程序有 iOS 租借应用,则此字段为必填字段。
|
rental_apps.ios.store_uri |
URI | 必需 | 可从中下载租借 iOS 应用的 URI。通常是应用商店(如 Apple App Store)的 URI。如果 URI 指向 Apple App Store 等应用商店,我们建议该 URI 遵循 iOS 最佳做法,以便查看应用可以直接打开原生应用商店应用(而非网站)。 |
rental_apps.ios.discovery_uri |
URI | 必需 | 采用 your_custom_scheme:// 格式的 URI。UIApplication canOpenURL: 可以使用该 URI 发现设备上是否安装了租借的 iOS 应用。
|
必需:free_bike_status.json (Dockless system)
请根据需要参阅 GBFS 规范。
此 Feed 定义了可用的独立式车辆的位置和属性。出于隐私保护方面的原因,有效租借的车辆不能出现在此 Feed 中。
字段名称 | 类型 | 要求 | 说明 |
---|---|---|---|
bikes |
数组 | 必需 | 一组当前可用的已停止自行车,其中每辆自行车都是一个对象。 |
bikes[].bike_id |
ID | 必需 | 自行车的标识符。
为了保护隐私,每次行程后,都可以将 ID 更改为随机字符串。 |
bikes[].lat |
纬度 | 必需 | 自行车的 WGS 84 纬度,采用小数度数格式。 |
bikes[].lon |
经度 | 必需 | 自行车的 WGS 84 经度,采用十进制的度数格式。 |
bikes[].is_reserved |
布尔值 | 必需 | 自行车是否已被预留,如下所示:
|
bikes[].is_disabled |
布尔值 | 必需 | 自行车当前是否被停用,具体如下:
|
bikes[].rental_uris |
对象 | 必需 | 一个 JSON 对象,分别在 Android、iOS 和 Web 的相应字段中包含租借 URI。 |
bikes[].rental_uris.android |
URI | Conditionally required | 可以通过 android.intent.action.VIEW Android intent 传递到 Android 应用以支持 Android 深层链接的 URI。提供的 rental_uris 必须是 Android App Links,这样一来,如果用户未安装提供程序应用,查看应用就无需手动管理将用户重定向到应用商店的重定向。
此 URI 必须是具体自行车的深层链接,而不是包含多辆自行车相关信息的常规租借页面。 深层链接必须直接将用户引导至自行车,且不提示用户、插页或登录。确保用户即使从未打开过应用,也能看到自行车。 URI 不一定需要包含自行车的 如果合作伙伴有 Android 租借应用,则必须填写此字段。 Android App Links 示例:
|
bikes[].rental_uris.ios |
URI | Conditionally required | 可在 iOS 上启动自行车租借应用的 URI。
如需了解详情,请参阅 Apple 有关 iOS 自定义网址架构的文章。
提供的 rental_uris 必须是 iOS 通用链接,这样在未安装提供程序应用的情况下,观看应用无需手动管理将用户重定向到应用商店的重定向。
此 URI 必须是具体自行车的深层链接,而不是包含多辆自行车相关信息的常规租借页面。 深层链接必须直接将用户引导至自行车,且不提示用户、插页或登录。确保用户即使从未打开过应用,也能看到自行车。 URI 不一定要包含自行车的自行车 ID,只要合作伙伴以其他方式标识各自的自行车即可。例如,租借应用可以使用 URI 中的其他标识符来唯一标识自行车。 如果合作伙伴有 iOS 租借应用,则必须填写此字段。 iOS 通用链接示例:
|
bikes[].rental_uris.web |
网址 | 选填 | 网址,可供网络浏览器用于显示有关在这辆车上租车的更多信息。 此网址必须是具体自行车的专用链接,而不是包含多辆自行车相关信息的通用租借页面。 深层链接必须直接将用户引导至自行车,且不提示用户、插页或登录。确保用户即使从未打开过应用,也能看到自行车。 网址未必必须包含自行车的 如果未设置此字段,则表示网络浏览器不支持深层链接。 示例值:
|
bikes[].vehicle_type_id |
ID | 必需 | 车辆的 vehicle_type_id (如 vehicle_types.json 部分所述)。
|
bikes[].pricing_plan_id |
ID | 必需 | 租借此类车辆时所采用的价格方案的标识符(如system_pricing_plans.json 部分中所述)。
|
bikes[].current_range_meters |
非负浮点数 | Conditionally required | 如果车辆对应的 vehicle_type 定义包含电机,则必须填写此字段。
根据车辆的当前充电量或油位,将距离设置为车辆可以行驶的最远距离(以米为单位)。 |
bikes[].last_reported |
时间戳 | 选填 | 设置为车辆上次向运营商后端报告其状态的时间。 |
以下是 free_bike_status.json
的示例:
"bikes": [{
"bike_id": "xyz123",
"lat": 12.34,
"lon": 56.78,
"is_reserved": true,
"is_disabled": false,
"rental_uris":{
"android": "https://www.example.com/app?sid=1234567890&platform=android",
"ios": "https://www.example.com/app?sid=1234567890&platform=ios",
"web": "https://www.example.com/app?sid=1234567890"
},
"vehicle_type_id": "scooter_electric",
"pricing_plan_id": "sydneyPlan1",
"current_range_meters": 4500,
"last_reported": 1434054678
},
{
"bike_id": "abc123",
"lat": 1.34,
"lon": 146.78,
"is_reserved": false,
"is_disabled": true,
"rental_uris":{
"android": "https://www.example.com/app?sid=1234567890&platform=android",
"ios": "https://www.example.com/app?sid=1234567890&platform=ios",
"web": "https://www.example.com/app?sid=1234567890"
},
"vehicle_type_id": "bike_manual",
"pricing_plan_id": "sydneyPlan1",
"last_reported": 1434054241
}
]
必需:vehicle_types.json(停靠和无基座系统)
请根据需要参阅 GBFS 规范。
此 Feed 定义了各个车辆类型的详细信息,请参阅 free_bike_status.json
部分。
字段名称 | 类型 | 要求 | 说明 |
---|---|---|---|
vehicle_types |
数组 | 必需 | 一个对象数组,其中每个对象都在提供商的目录中定义一种不同的车辆类型。对于给定的车辆类型,只能有一个对象。 |
vehicle_types[].vehicle_type_id |
ID | 必需 | 给定车辆类型的唯一标识符。 |
vehicle_types[].form_factor |
Enum | 必需 | 一个表示车辆通用类型的枚举,来自以下当前有效的值列表:
|
vehicle_types[].propulsion_type |
Enum | 必需 | 表示车辆主要动力类型的枚举,来自以下当前有效的值列表:
|
vehicle_types[].max_range_meters |
非负浮点数 | Conditionally required | 如果 propulsion_type 未设置为 human ,则车辆具有电机,因此此字段为必填字段。
当车辆完全充满电或充满电时,设置为车辆可以行驶的最远距离(以米为单位)。 |
以下是 vehicle_types.json
的示例:
"vehicle_types": [
{
"vehicle_type_id": "bike_manual",
"form_factor": "bicycle",
"propulsion_type": "human"
},
{
"vehicle_type_id": "scooter_electric",
"form_factor": "scooter",
"propulsion_type": "electric",
"max_range_meters": 10000
}
]
必需:system_pricing_plans.json(基座系统)
请根据需要参阅 GBFS 规范。
此 Feed 指定了独立车辆的价格方案。我们要求提供商显示独立车辆的价格信息。
字段名称 | 类型 | 要求 | 说明 |
---|---|---|---|
plans |
数组 | 必需 | 一个对象数组,其中每个对象都定义了指定的价格方案。 |
plans[].plan_id |
ID | 必需 | 一个字符串,表示提供商提供的指定价格方案的唯一标识符。 |
plans[].url |
网址 | 选填 | 指向最终用户的网址,以便用户详细了解价格方案。 |
plans[].currency |
字符串 | 必需 | 价格方案的 ISO 4217 标准。 |
plans[].price |
非负浮点数 | 必需 |
价格方案必须定义为无费率价格方案或评分价格方案:
|
plans[].per_km_pricing |
数组 | Conditionally required |
如果价格是行程距离的函数(以公里为单位),则此字段为必填字段。 一组对象,其中每个对象定义给定的距离分割线段。每个片段的 如需确定给定方案的总价格,请将指定方案的 如果未设置此字段,则不存在基于距离的可变价格,因此这些价格均未包含在总价中。 |
plans[].per_km_pricing[].start |
非负整数 | 必需 |
开始计费的细分受众群公里数。此字段设置为启动细分受众群范围的包含值。因此,经过公里数后,rate 会收费一次。 |
plans[].per_km_pricing[].rate |
浮点值 | 必需 | 为每个 interval (从此细分受众群的包含 start 开始)收取的费率。如果此字段设置为负数,旅客将获得折扣。
|
plans[].per_km_pricing[].interval |
非负整数 | 必需 |
无限地重新应用细分的
如果此细分受众群的 如果此字段设置为 |
plans[].per_km_pricing[].end |
非负整数 | 选填 |
相应路段的 如果此字段未设置或为空,细分受众群的 |
plans[].per_min_pricing |
数组 | Conditionally required |
如果价格是经过的时间(以分钟为单位)的函数,则此字段为必填字段。 一组对象,其中每个对象定义一个给定的时间细分段。每个片段的 如需确定给定方案的总价格,请将指定方案的 如果未设置此字段,则不存在基于时间的可变价格,因此价格不会包含在总价中。 |
plans[].per_min_pricing[].start |
浮点值 | 必需 |
开始对细分受众群费率收费的分钟数。此字段设置为启动细分受众群范围的包含值。因此,在设置的分钟数过后,rate 会计费一次。 |
plans[].per_min_pricing[].rate |
浮点值 | 必需 | 每个interval 的费率。此费率从此细分的 start (含)开始计算。如果此字段设置为负数,旅客将获得折扣。
|
plans[].per_min_pricing[].interval |
非负整数 | 必需 |
无限期地重新应用细分的
如果此细分受众群的 如果此字段设置为 |
plans[].per_min_pricing[].end |
非负整数 | 选填 |
此时,系统不再应用片段的 如果此字段未设置或为空,细分受众群的 |
system_pricing_plans.json 示例
本部分提供了详实的 system_pricing_plans.json
代码示例。此外,还提供了每个示例的相关详细信息和结果。
system_pricing_plans.json 的示例 1
以下价格方案代码示例根据历程中的以下时间间隔显示费用:
- [0,1):2 元
- 如果旅程少于 1 分钟,用户需支付 2 美元。
- 示例:行程 59 秒
- [1,2):3 元
- 如果历程超过或等于一分钟但不到两分钟,则用户需要支付 $2 + $1 = $3 美元。
- 示例:行程 1 分钟;行程 1 分钟 45 秒
- x 大于或等于 2 的分钟数:$3 + ($2 + $1) * (x - 2 + 1)) USD
- 如果旅程超过或等于两分钟,则用户需要为行程中不到两分钟的部分支付 3 美元的费用,并且每两分钟需要支付 2 美元 [
per_min_pricing
列表的第二个条目] + 2 美元 [即per_min_pricing
列表的第二个条目]。 - 示例:
- 2 分钟行程费用:3 美元 +(2 美元 + 1 美元)= 6 美元
- 2 分钟 30 秒的行程费用为 $3 + ($2 + $1) = $6 美元
- 3 分钟行程费用:3 美元 +(2 美元 + 1 美元 * 2)= 9 美元
- 10 分钟的行程费用为 $3 + ($2 + $1) * 9) = $30 USD
- 如果旅程超过或等于两分钟,则用户需要为行程中不到两分钟的部分支付 3 美元的费用,并且每两分钟需要支付 2 美元 [
{
"plans": {
"plan_id": "plan1",
"currency": "USD",
"price": 2,
"per_min_pricing": [
{
"interval": 1,
"rate": 1,
"start": 1
},
{
"interval": 1,
"rate": 2,
"start": 2
}
],
}
}
system_pricing_plans.json 的示例 2
在此示例中,我们显示一个代码示例,以按分钟和公里费率收费的价格方案:
- 具体而言,最终用户需支付每公里 0.25 加元和每分钟 $0.50 加元的费用。
- 这两种速率同时发生,并且互不依赖。
- 因此,每公里行程 1 公里,费用为 9 加元。费用明细如下:
- 基础价格:3 美元
- $0.25 * 2,在行程开始时收取一次费用,在 1 公里处收取一次费用。
- $0.5 * 11,每分钟收费一次。充电从 0 秒开始,按 10 分钟计费。
{
"plans": {
"plan_id": "plan2",
"currency": "CAD",
"price": 3,
"per_km_pricing": [{
"start": 0,
"rate": 0.25,
"interval": 1
}],
"per_min_pricing": [{
"start": 0,
"rate": 0.50,
"interval": 1
}]
}
}
视情况而定:geofencing_zones.json(停靠和无基座系统)
请根据需要参阅 GBFS 规范。
此 Feed 定义了独立车辆的地理围栏数据。地理围栏数据指定了允许车辆开始和完成骑行的地理边界,以及车辆可以行驶的速度。此速度是车辆的最高速度或车辆行驶道路上的速度限制,以较低者为准。驾驶员必须遵守当地法律和法规。
我们使用此数据,这样一来,当用户搜索给定路线时,如果行程结束点位于特定地理围栏之外,系统会滤除“机动性”结果。如果未提供地理围栏,Google 会认为该服务没有边界限制。
字段名称 | 类型 | 要求 | 说明 |
---|---|---|---|
geofencing_zones |
对象 | 必需 | FeatureCollection 对象(如 IETF RFC 7946 中所述)具有一个名为 features 的字段。features 的值是一个 JSON 数组。JSON 数组的每个元素都是一个 Feature 对象。每个地理围栏可用区及其关联的规则和属性以及 |
geofencing_zones.type |
字符串 | 必需 | 设置为 IETF RFC 7946 中所述的 FeatureCollection 。 |
geofencing_zones.features |
数组 | 必需 | 一个 JSON 数组,其中 JSON 数组的每个元素都是一个 Feature 对象。 |
geofencing_zones.features[].type |
字符串 | 必需 | 设置为 IETF RFC 7946 中所述的 Feature 。 |
geofencing_zones.features[].geometry |
GeoJSON 多多边形 | 必需 | 一个 GeoJSON 多多边形,描述了骑行的开始、结束和经过位置以及其他限制。点的顺时针排列定义多边形封闭的区域,而逆时针顺序定义多边形以外的区域。如需了解详情,请参阅右侧规则。 |
geofencing_zones.features[].properties |
对象 | 必需 | 用于定义旅行允许限额和限制的对象。 |
geofencing_zones.features[].properties.rules |
数组 | 选填 | 对象数组,其中每个对象仅定义一个规则。如果两条或更多规则以某种方式发生重叠、冲突或以其他方式冲突,则以 JSON 文件顺序最早的规则为准。 |
geofencing_zones.features[].properties.rules[].vehicle_type_id |
数组 | 选填 | 一组车辆类型 ID,其中每个元素都是一个 vehicle_type_id ,必须对其应用任何限制。如果未指定 vehicle_type_id ,则这些限制适用于所有车辆类型。 |
geofencing_zones.features[].properties.rules[].ride_allowed |
布尔值 | 必需 | 独立式“停靠式”自行车骑行是否可以在该区域开始和结束,如下所示:
|
以下是 geofencing_zones.json
的示例:
"geofencing_zones":{
"type":"FeatureCollection",
"features":[{
"type":"Feature",
"properties":{
"rules":[{
"vehicle_type_id":"scooter",
"ride_allowed": false
}]
},
"geometry":{
"type":"MultiPolygon",
"coordinates":[[[
[-122.66780376434326, 45.49896266763551],
[-122.66810417175292, 45.49824825558575],
[-122.66830801963805, 45.49632305799116],
[-122.66780376434326, 45.49896266763551]
]]]
}
}]
}
必需:station_information.json(停靠系统)
请根据需要参阅 GBFS 规范。
此 Feed 定义了有关公共共享单车站点的一般信息。
字段名称 | 类型 | 要求 | 说明 |
---|---|---|---|
stations |
数组 | 必需 | 一个对象数组,其中每个对象定义的都是一个电台,且只定义一个电台。 |
stations[].station_id |
字符串 | 必需 | 电台的标识符。 |
stations[].name |
字符串 | 必需 |
车站所在城市当地语言的公开名称。name 必须遵循车站的标识牌上的信息(如果有),或者必须使用十字路口或当地地标来反映车站的位置。不要将“St.”等缩写用于“街道”,除非在标识牌中明确使用缩写,并且 name 必须采用混合大小写形式,以便遵循地点名称的大小写规范,而不是全部大写。
|
stations[].lat |
纬度 | 必需 | 充电站的 WGS 84 纬度,采用十进制的度数格式。 |
stations[].lon |
经度 | 必需 | 充电站的 WGS 84 经度,采用十进制的度数格式。 |
stations[].capacity |
非负整数 | 选填 | 非负整数,表示在电台安装的坞站总数(包括可用和不可用的基座)。 |
stations[].rental_uris |
对象 | 必需 |
一个 JSON 对象,分别在 Android、iOS 和 Web 的相应字段中包含租借 URI。 如果指定了这些 URI,则它们会替换提供商初始配置时设置的默认深层链接。 |
stations[].rental_uris.android |
URI | Conditionally required |
可以通过 此 URI 必须是具体电台的深层链接,而不是包含多个电台信息的常规租借页面。深层链接必须让用户直接转到电台,而无需任何提示、插页或登录。确保用户从来没有打开过应用,也能查看电台。 URI 不一定需要包含电台的 如果合作伙伴有 Android 租借应用,则必须填写此字段。 Android App Links 示例:
|
stations[].rental_uris.ios |
URI | Conditionally required |
可在 iOS 上用于为电台启动租借应用的 URI。
如需了解详情,请参阅 Apple 有关 iOS 自定义网址架构的文章。
提供的 此 URI 必须是具体电台的深层链接,而不是包含多个电台信息的常规租借页面。深层链接必须让用户直接转到电台,而无需任何提示、插页或登录。确保用户从来没有打开过应用,也能查看电台。 URI 不一定需要包含电台的 如果合作伙伴有 iOS 租借应用,则必须填写此字段。 iOS 通用链接示例:
|
stations[].rental_uris.web |
网址 | 选填 | 网址,可供网络浏览器用于显示有关如何在此站租车的更多信息。 此网址必须是具体电台的深层链接,而不是包含多个电台信息的通用租借页面。 深层链接必须让用户直接转到电台,而无需任何提示、插页或登录。确保用户从来没有打开过应用,也能查看电台。 网址不一定要包含电台的 如果未设置此字段,则表示网络浏览器不支持深层链接。 示例值:
|
以下是 station_information.json
的示例:
"stations": [
{
"station_id": "597",
"name": "Silverthorne Road, Battersea",
"lat": 51.472865,
"lon": -0.148059,
"capacity": 10,
"rental_uris": {
"android": "https://www.example.com/app?sid=1234567890&platform=android",
"ios": "https://www.exampleexample.com/app?sid=1234567890&platform=ios",
"web": "https://www.example.com/app?sid=1234567890&platform=web"
}
},
]
必需:station_status.json(基座系统)
请根据需要参阅 GBFS 规范。
此 Feed 定义了公共共享单车站点的最新状态。
字段名称 | 类型 | 要求 | 说明 |
---|---|---|---|
stations |
数组 | 必需 | 一个对象数组,其中每个对象仅定义一个电台。 |
stations[].station_id |
字符串 | 必需 | 电台的标识符。 |
stations[].num_bikes_available |
非负整数 | 必需 |
一个非负整数,表示实际位于站点且可能可供租赁的多功能自行车的数量。 如需确定该站点当前是否租赁自行车,您必须检查该站点的 |
stations[].vehicle_types_available |
数组 | 选填 |
定义车辆总数的对象数组,按充电站提供的各车辆类型进行分类。每个对象都会根据关联的车辆类型对车辆总数进行建模。这些对象中的车辆总数必须相加,与 |
stations[].vehicle_types_available[].vehicle_type_id |
ID | 必需 |
车站支持的各车辆类型的 |
stations[].vehicle_types_available[].count |
非负整数 | 必需 |
站内相应 |
stations[].num_docks_available |
非负整数 | Conditionally required |
此字段是必填字段,除非电台的基座容量不受限制。例如,虚拟工作站的基座容量不受限制,并且此字段并非必填字段。 一个非负整数,表示该站点中能够接受车辆退役的实际功能基座总数。 如需确定车站目前是否接受自行车退货,您必须检查其 |
stations[].is_installed |
布尔值 | 必需 |
一个布尔值,用于指示车站当前是否在街道上且已安装。 如果街道上已安装该电台,请将其设置为 如果街道上未安装该电台,请将其设置为 |
stations[].is_renting |
布尔值 | 必需 |
指示车辆当前是否租赁自行车的布尔值。 如果此站目前提供自行车租赁服务,请设置为 如果充电站目前没有租自行车,请设置为 |
stations[].is_returning |
布尔值 | 必需 |
一个布尔值,用于指示车站当前是否接受自行车退货。 如果车站当前接受自行车退车,请设置为 如果充电站目前不接受自行车退货,请设置为 |
以下是 station_status.json
的示例:
"stations": [
{
"station_id": "2",
"num_bikes_available": 6,
"vehicle_types_available": [
{
"vehicle_type_id" : "scooter_electric",
"count" : 2
},
{
"vehicle_type_id" : "bike_manual",
"count" : 4
}
],
"num_docks_available": 30,
"is_installed": true,
"is_renting": true,
"is_returning": true,
"last_reported": 1576119631
},
]