Định nghĩa về GBFS

Trước khi tiếp tục với phần này, nếu chưa thực hiện, hãy xác minh các hệ thống di chuyển siêu nhỏ được hỗ trợ mà bạn đang tạo nguồn cấp dữ liệu.

Trong các phần sau, mỗi tiêu đề đều có định dạng sau: Required|Optional|Conditionally required: Feed name (System supported). Các hệ thống sau đây được hỗ trợ:

  • Hệ thống được gắn đế
  • Hệ thống không cần đế sạc
  • Hệ thống có trạm sạc và không có trạm sạc

Để tích hợp thành công với Google, bạn chỉ cần cung cấp những tệp cần thiết cho hệ thống mà nguồn cấp dữ liệu của bạn mô tả và chỉ định các trường bắt buộc có trong các phần liên quan. Đối với các trường bắt buộc có điều kiện, hãy tham khảo phần mô tả của trường để biết hướng dẫn. Bạn cũng có thể chỉ định các trường không bắt buộc để thêm thông tin và mang lại trải nghiệm người dùng tốt hơn.

Tiêu đề bắt buộc đối với nguồn cấp dữ liệu Micromobility

Nguồn cấp dữ liệu về phương tiện di chuyển siêu nhỏ là nguồn cấp dữ liệu chứa dữ liệu có cấu trúc về phương tiện di chuyển siêu nhỏ có hoặc không có trạm sạc như được xác định trong bài viết này.

Tất cả nguồn cấp dữ liệu phải luôn chỉ định các trường có trong bảng sau ở cấp cao nhất của đối tượng JSON, được gọi chung là tiêu đề GBFS chung.

Tên trường Loại Yêu cầu Mô tả
last_updated Dấu thời gian Bắt buộc Dấu thời gian POSIX, chỉ định số giây kể từ 00:00:00 ngày 1 tháng 1 năm 1970 (theo giờ UTC).

Đặt thành lần gần đây nhất dữ liệu trong nguồn cấp dữ liệu được cập nhật.
ttl Số nguyên không âm Bắt buộc Một số nguyên không âm biểu thị số giây còn lại cho đến thời điểm cập nhật nguồn cấp dữ liệu.

Nếu dữ liệu phải được cập nhật với tốc độ không đổi, hãy đặt giá trị này thành 0.
data JSON Bắt buộc JSON chứa các trường dữ liệu cho từng nguồn cấp dữ liệu.

Ví dụ: một nguồn cấp dữ liệu free_bike_status.json tổng hợp chỉ định tiêu đề GBFS chung có thể như sau:

{
    "ttl": 30,
    "last_updated": 1576123774,
    "data": {
        "bikes": [ ... ]  // GBFS free bike status objects.
    }
}

Bắt buộc: system_information.json (Hệ thống có đế sạc và không có đế sạc)

Tham khảo quy cách GBFS nếu cần.

Nguồn cấp dữ liệu này cung cấp thông tin chi tiết về người vận hành hệ thống.

Tên trường Loại Yêu cầu Mô tả
system_id Mã nhận dạng Bắt buộc Giá trị nhận dạng duy nhất trên toàn cầu cho hệ thống chia sẻ xe. Giá trị này dự kiến sẽ không thay đổi trong suốt vòng đời của hệ thống. Mỗi hệ thống hoặc khu vực địa lý riêng biệt nơi xe hoạt động PHẢI có system_id riêng. Bạn CẦN nhận dạng được mã nhận dạng hệ thống là thuộc về một hệ thống cụ thể chứ không phải chuỗi ngẫu nhiên – ví dụ: bcycle_austin hoặc biketown_pdx.
name Chuỗi Bắt buộc Tên của hệ thống mà khách hàng nhìn thấy.
rental_apps Đối tượng Bắt buộc Một đối tượng JSON chứa thông tin của ứng dụng cho thuê cho Android và iOS trong các trường tương ứng.
rental_apps.android Đối tượng Bắt buộc có điều kiện Chứa thông tin về lượt tải ứng dụng cho thuê và thông tin khám phá ứng dụng cho nền tảng Android trong các trường store_uri và discovery_uri. Nếu nhà cung cấp hệ thống có một ứng dụng cho thuê trên Android, thì bạn phải điền trường này.
rental_apps.android.store_uri URI Bắt buộc URI nơi có thể tải ứng dụng Android cho thuê xuống. Đây thường là một URI đến một cửa hàng ứng dụng, chẳng hạn như Google Play. Nếu URI trỏ đến một cửa hàng ứng dụng như Google Play, bạn nên tuân theo các phương pháp hay nhất của Android để ứng dụng xem có thể trực tiếp mở URI đến ứng dụng cửa hàng ứng dụng gốc thay vì một trang web.
rental_apps.android.discovery_uri URI Bắt buộc URI có dạng your_custom_scheme://your/path/here. PackageManager.queryIntentActivities() có thể dùng URI này để phát hiện xem ứng dụng Android cho thuê đã được cài đặt trên thiết bị hay chưa.
rental_apps.ios Đối tượng Bắt buộc có điều kiện Chứa thông tin về lượt tải ứng dụng cho thuê và thông tin khám phá ứng dụng cho nền tảng iOS trong các trường store_uri và discovery_uri. Nếu nhà cung cấp hệ thống có ứng dụng cho thuê trên iOS, thì bạn phải điền trường này.
rental_apps.ios.store_uri URI Bắt buộc URI nơi có thể tải ứng dụng cho thuê trên iOS xuống. Đây thường là một URI đến một cửa hàng ứng dụng, chẳng hạn như Apple App Store. Nếu URI trỏ đến một cửa hàng ứng dụng như Apple App Store, thì bạn nên để URI tuân theo các phương pháp hay nhất của iOS để ứng dụng xem có thể trực tiếp mở URI đến ứng dụng cửa hàng ứng dụng gốc thay vì một trang web.
rental_apps.ios.discovery_uri URI Bắt buộc URI có dạng your_custom_scheme://. UIApplication canOpenURL: có thể dùng URI này để phát hiện xem ứng dụng iOS cho thuê đã được cài đặt trên thiết bị hay chưa.

Bắt buộc: free_bike_status.json (Hệ thống không có trạm sạc)

Tham khảo quy cách GBFS nếu cần.

Nguồn cấp dữ liệu này xác định vị trí và thuộc tính của các phương tiện độc lập hiện có. Vì lý do liên quan đến quyền riêng tư, những chiếc xe đang được cho thuê không được xuất hiện trong nguồn cấp dữ liệu này.

Tên trường Loại Yêu cầu Mô tả
bikes Mảng Bắt buộc Một mảng gồm các xe đạp hiện có và đã dừng, trong đó mỗi xe đạp là một đối tượng.
bikes[].bike_id Mã nhận dạng Bắt buộc Giá trị nhận dạng của xe đạp.

Để bảo vệ quyền riêng tư, mã nhận dạng có thể được thay đổi thành một chuỗi ngẫu nhiên sau mỗi chuyến đi.
bikes[].lat Vĩ độ Bắt buộc Vĩ độ WGS 84 của xe đạp, ở định dạng độ thập phân.
bikes[].lon Kinh độ Bắt buộc Kinh độ WGS 84 của xe đạp, ở định dạng độ thập phân.
bikes[].is_reserved Boolean Bắt buộc Xe đạp có đang được đặt trước hay không, như sau:
  • Nếu xe đạp hiện đang được đặt trước, hãy đặt thành true.
  • Nếu xe đạp hiện chưa được đặt trước, hãy đặt thành false.
bikes[].is_disabled Boolean Bắt buộc Xe đạp hiện đang bị vô hiệu hoá hoặc hỏng hóc hay không, như sau:
  • Nếu xe đạp hiện đang ở trạng thái tắt, hãy đặt thành true.
  • Nếu xe đạp hiện không bị vô hiệu hoá, hãy đặt thành false.
bikes[].rental_uris Đối tượng Bắt buộc Một đối tượng JSON chứa URI cho thuê cho Android, iOS và web trong các trường tương ứng.
bikes[].rental_uris.android URI Bắt buộc có điều kiện Một URI có thể được truyền đến ứng dụng Android bằng ý định android.intent.action.VIEW của Android để hỗ trợ Đường liên kết sâu của Android. rental_uris được cung cấp phải là Đường liên kết đến ứng dụng Android để ứng dụng xem không cần quản lý thủ công việc chuyển hướng người dùng đến cửa hàng ứng dụng trong trường hợp người dùng chưa cài đặt ứng dụng của nhà cung cấp.

URI này phải là một đường liên kết sâu dành riêng cho từng xe đạp, chứ không phải là một trang cho thuê chung có thông tin cho nhiều xe đạp. Đường liên kết sâu phải đưa người dùng đến thẳng xe đạp mà không cần đến lời nhắc, trang xen kẽ hay thao tác đăng nhập. Đảm bảo rằng người dùng có thể nhìn thấy xe đạp ngay cả khi họ chưa từng mở ứng dụng.

Bạn không nhất thiết phải thêm bike_id cho xe đạp vào URI, miễn là đối tác có những cách khác để xác định xe đạp tương ứng. Ví dụ: ứng dụng cho thuê có thể sử dụng các giá trị nhận dạng khác trong URI để xác định duy nhất xe đạp.

Nếu đối tác có ứng dụng cho thuê trên Android, thì bạn phải điền trường này.

Ví dụ về Đường liên kết trong ứng dụng Android:

https://www.example.com/app?sid=1234567890&platform=android
bikes[].rental_uris.ios URI Bắt buộc có điều kiện Một URI có thể dùng trên iOS để chạy ứng dụng cho thuê xe đạp. Để biết thêm thông tin về vấn đề này, hãy tham khảo bài viết của Apple về lược đồ URL tuỳ chỉnh của iOS. rental_uris được cung cấp phải là Đường liên kết phổ quát trên iOS để ứng dụng xem không cần quản lý thủ công việc chuyển hướng người dùng đến cửa hàng ứng dụng trong trường hợp người dùng chưa cài đặt ứng dụng của nhà cung cấp.

URI này phải là một đường liên kết sâu dành riêng cho từng xe đạp, chứ không phải là một trang cho thuê chung có thông tin cho nhiều xe đạp. Đường liên kết sâu phải đưa người dùng đến thẳng xe đạp mà không cần đến lời nhắc, trang xen kẽ hay thao tác đăng nhập. Đảm bảo rằng người dùng có thể nhìn thấy xe đạp ngay cả khi họ chưa từng mở ứng dụng.

URI không nhất thiết phải bao gồm bike_id cho xe đạp, miễn là đối tác có những cách khác để xác định xe đạp tương ứng. Ví dụ: ứng dụng cho thuê có thể sử dụng các giá trị nhận dạng khác trong URI để xác định xe đạp một cách duy nhất.

Nếu đối tác có ứng dụng cho thuê trên iOS, thì bạn phải điền trường này.

Ví dụ về Đường liên kết phổ quát trên iOS:

https://www.example.com/app?sid=1234567890&platform=ios

bikes[].rental_uris.web URL Không bắt buộc

URL mà trình duyệt web có thể dùng để cho biết thêm thông tin về việc thuê xe tại địa điểm này.

URL này phải là một đường liên kết sâu dành riêng cho từng xe đạp, không phải là một trang cho thuê chung có thông tin cho nhiều xe đạp. Đường liên kết sâu phải đưa người dùng đến thẳng xe đạp mà không cần đến lời nhắc, trang xen kẽ hay thao tác đăng nhập. Đảm bảo rằng người dùng có thể nhìn thấy xe đạp ngay cả khi họ chưa từng mở ứng dụng.

Bạn không nhất thiết phải thêm bike_id vào URL cho xe đạp hoặc tuân theo các quy ước ngữ nghĩa của URL cho thuê cho Android hoặc iOS. Ứng dụng cho thuê có thể sử dụng các giá trị nhận dạng khác trong URL để xác định duy nhất xe đạp.

Nếu bạn không đặt trường này, tức là trình duyệt web không hỗ trợ đường liên kết sâu.

Giá trị mẫu:

https://www.example.com/app?sid=1234567890
bikes[].vehicle_type_id Mã nhận dạng Bắt buộc vehicle_type_id của xe như mô tả trong phần vehicle_types.json.
bikes[].pricing_plan_id Mã nhận dạng Bắt buộc Giá trị nhận dạng của gói giá được áp dụng khi loại xe này được cho thuê như mô tả trong phần system_pricing_plans.json.
bikes[].current_range_meters Số thực không âm Bắt buộc có điều kiện Nếu định nghĩa vehicle_type tương ứng với xe có động cơ, thì bạn phải điền trường này.

Đặt thành khoảng cách xa nhất (tính bằng mét) mà xe có thể đi được mà không cần sạc lại hoặc đổ thêm nhiên liệu, dựa trên mức sạc hoặc mức nhiên liệu hiện tại của xe.
bikes[].last_reported Dấu thời gian Không bắt buộc Đặt thành lần gần đây nhất mà xe báo cáo trạng thái của xe cho hệ thống phụ trợ của nhà điều hành.

Sau đây là một ví dụ về 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
}
]

Bắt buộc: vehicle_types.json (Hệ thống có giá đỡ và không có giá đỡ)

Tham khảo quy cách GBFS nếu cần.

Nguồn cấp dữ liệu này xác định thông tin chi tiết về từng loại xe riêng lẻ, như được đề cập trong phần free_bike_status.json.

Tên trường Loại Yêu cầu Mô tả
vehicle_types Mảng Bắt buộc Một mảng các đối tượng, trong đó mỗi đối tượng xác định một loại xe riêng biệt trong danh mục của nhà cung cấp. Chỉ có thể có một đối tượng cho một loại xe nhất định.
vehicle_types[].vehicle_type_id Mã nhận dạng Bắt buộc Giá trị nhận dạng riêng biệt cho một loại xe nhất định.
vehicle_types[].form_factor Enum Bắt buộc Một enum đại diện cho hệ số hình dạng chung của xe, trong danh sách các giá trị hợp lệ hiện tại sau đây:
  • bicycle
  • scooter
  • other
vehicle_types[].propulsion_type Enum Bắt buộc Một enum đại diện cho loại lực đẩy chính của xe, trong danh sách các giá trị hợp lệ hiện tại sau đây:
  • human: Lực đẩy từ bàn đạp hoặc chân
  • electric_assist: Chỉ cung cấp năng lượng cùng với lực đẩy của con người
  • electric: Có chế độ ga với động cơ chạy bằng pin
  • combustion: Chứa chế độ ga với động cơ chạy bằng xăng
vehicle_types[].max_range_meters Số thực không âm Bắt buộc có điều kiện Nếu propulsion_type không được đặt thành human, thì xe có động cơ và do đó, bạn bắt buộc phải sử dụng trường này.

Đặt thành khoảng cách xa nhất mà xe có thể đi được (tính bằng mét) mà không cần sạc lại hoặc đổ thêm nhiên liệu, khi xe đã đổ đầy nhiên liệu hoặc sạc đầy.

Sau đây là một ví dụ về 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
  }
]

Bắt buộc: system_pricing_plans.json (Hệ thống không có trạm sạc)

Tham khảo quy cách GBFS nếu cần.

Nguồn cấp dữ liệu này xác định các gói giá cho xe tự lái. Chúng tôi yêu cầu các nhà cung cấp đăng thông tin về giá cho những chiếc xe độc lập.

Tên trường Loại Yêu cầu Mô tả
plans Mảng Bắt buộc Một mảng gồm các đối tượng, trong đó mỗi đối tượng xác định một gói giá nhất định.
plans[].plan_id Mã nhận dạng Bắt buộc Một chuỗi đại diện cho giá trị nhận dạng duy nhất của gói giá mà nhà cung cấp đưa ra.
plans[].url URL Không bắt buộc URL chuyển người dùng cuối đến trang cung cấp thêm thông tin về gói giá.
plans[].currency Chuỗi Bắt buộc Tiêu chuẩn ISO 4217 cho gói giá.
plans[].price Số thực không âm Bắt buộc

Bạn phải xác định gói giá là gói giá không được xếp hạng hoặc gói giá được xếp hạng:

Gói giá không được xếp hạng

Đây là gói có một mức giá cố định.

Đặt trường sau:

  • price: Giá cố định của toàn bộ chuyến đi.
Gói giá được phân loại

Đây là gói có giá theo tỷ lệ tuyến tính từng phần.

Đặt trường sau:

  • price: Giá cơ bản, chỉ tính một lần cho mỗi chuyến đi.

Đặt một hoặc cả hai trường sau:

  • per_km_pricing: Giá của chuyến đi được chỉ định theo mức giá mỗi km.
  • per_min_pricing: Giá của chuyến đi được chỉ định theo mức giá mỗi phút.
plans[].per_km_pricing Mảng Bắt buộc có điều kiện

Nếu giá là một hàm của quãng đường đã đi, được hiển thị bằng ki-lô-mét, thì bạn phải điền thông tin vào trường này.

Một mảng các đối tượng, trong đó mỗi đối tượng xác định một đoạn được chia theo khoảng cách nhất định. Giá trị start của mỗi phân khúc phải nhỏ hơn hoặc bằng giá trị start của phân khúc tiếp theo.

Để xác định tổng giá của gói đã cho, hãy thêm giá trị plans[].price của gói đã cho vào giá tích luỹ cho các phân khúc trong plans[].per_km_pricing và plans[].per_min_pricing.

Nếu bạn không đặt trường này, thì sẽ không có giá thay đổi dựa trên khoảng cách và do đó, không có giá nào được tính vào tổng giá.
plans[].per_km_pricing[].start Số nguyên không âm Bắt buộc Số ki-lô-mét mà mức giá theo đoạn đường bắt đầu được tính. Trường này được đặt thành giá trị bao gồm bắt đầu phạm vi của phân đoạn. Do đó, sau khi số km đã hết, rate sẽ được tính phí một lần.
plans[].per_km_pricing[].rate Số thực dấu phẩy động Bắt buộc Mức phí được tính cho mỗi interval, bắt đầu từ start (bao gồm cả) của phân đoạn. Nếu bạn đặt trường này thành một số âm, thì khách du lịch sẽ được giảm giá.
plans[].per_km_pricing[].interval Số nguyên không âm Bắt buộc

Khoảng thời gian tính bằng km mà rate của đoạn đường được áp dụng lại vô thời hạn, trừ phi end của đoạn đường được đặt thành một số nguyên không âm.

rate sẽ được áp dụng lại một lần khi bắt đầu mỗi interval và không có khoảng cách làm tròn nào được xem xét.

Nếu end của phân đoạn được đặt thành bất kỳ số nguyên không âm nào, thì rate của phân đoạn sẽ được áp dụng lại cho đến khi đạt đến giá trị end của phân đoạn (nhưng không bao gồm giá trị này).

Nếu bạn đặt trường này thành 0, thì rate sẽ được tính phí chính xác một lần tại start của đoạn.
plans[].per_km_pricing[].end Số nguyên không âm Không bắt buộc

Số ki-lô-mét tại thời điểm rate cho phân đoạn không còn được áp dụng. Trường này được đặt thành giá trị độc quyền kết thúc phạm vi của phân đoạn. Ví dụ: nếu end được đặt thành 40, thì rate sẽ không còn áp dụng ở khoảng cách 40 km.

Nếu bạn không đặt hoặc để trống trường này, thì rate cho đoạn đường sẽ được tính cho đến khi chuyến đi kết thúc, ngoài mọi đoạn đường bổ sung sau đó.
plans[].per_min_pricing Mảng Bắt buộc có điều kiện

Nếu giá là một hàm của thời gian đã trôi qua, được hiển thị bằng phút, thì bạn phải điền vào trường này.

Một mảng các đối tượng, trong đó mỗi đối tượng xác định một phân khúc được chia theo thời gian nhất định. Giá trị start của mỗi phân đoạn phải nhỏ hơn hoặc bằng giá trị start của phân đoạn tiếp theo.

Để xác định tổng giá của gói đã cho, hãy thêm giá trị plans[].price của gói đã cho vào giá tích luỹ cho các phân khúc trong plans[].per_km_pricing và plans[].per_min_pricing.

Nếu bạn không đặt trường này, thì sẽ không có giá linh hoạt dựa trên thời gian và do đó, không có giá nào được tính vào tổng giá.
plans[].per_min_pricing[].start Số thực dấu phẩy động Bắt buộc Số phút mà tốc độ phân đoạn bắt đầu được tính phí. Trường này được đặt thành giá trị bao gồm bắt đầu phạm vi của phân đoạn. Do đó, sau khi hết số phút đã đặt, rate sẽ được tính phí một lần.
plans[].per_min_pricing[].rate Số thực dấu phẩy động Bắt buộc Mức phí được tính cho mỗi interval. Tỷ lệ bắt đầu từ start (bao gồm) của phân đoạn. Nếu bạn đặt trường này thành một số âm, thì khách du lịch sẽ được giảm giá.
plans[].per_min_pricing[].interval Số nguyên không âm Bắt buộc

Khoảng thời gian tính bằng phút mà rate của phân khúc được áp dụng lại vô thời hạn, trừ phi end của phân khúc được đặt thành một số nguyên không âm.

rate sẽ được áp dụng lại một lần khi bắt đầu mỗi interval và không xem xét việc làm tròn thời gian di chuyển.

Nếu end của phân đoạn được đặt thành bất kỳ số nguyên không âm nào, thì rate của phân đoạn sẽ được áp dụng lại cho đến khi đạt đến giá trị end của phân đoạn (nhưng không bao gồm giá trị này).

Nếu bạn đặt trường này thành 0, thì rate sẽ được tính phí chính xác một lần tại start của đoạn.
plans[].per_min_pricing[].end Số nguyên không âm Không bắt buộc

Số phút mà rate cho phân đoạn không còn được áp dụng nữa. Trường này được đặt thành giá trị độc quyền kết thúc phạm vi của phân đoạn. Ví dụ: nếu end được đặt thành 20, thì rate sẽ không còn áp dụng sau 20 phút nữa.

Nếu bạn không đặt hoặc để trống trường này, thì rate cho đoạn đường sẽ được tính cho đến khi chuyến đi kết thúc, ngoài bất kỳ đoạn đường bổ sung nào sau đó.

Ví dụ về system_pricing_plans.json

Phần này cung cấp các đoạn mã mẫu system_pricing_plans.json mang tính thông tin. Thông tin chi tiết và kết quả có liên quan của từng ví dụ cũng được cung cấp.

Ví dụ 1 cho system_pricing_plans.json

Mã mẫu kế hoạch giá sau đây cho thấy các khoản phí dựa trên thời gian di chuyển cho các khoảng thời gian sau:

  • [0,1): 20.000 VND
    • Nếu hành trình dưới 1 phút, người dùng sẽ trả 2 USD.
    • Ví dụ: Chuyến đi 59 giây
  • [1,2): 3 USD
    • Nếu hành trình dài hơn hoặc bằng 1 phút nhưng ít hơn 2 phút, người dùng sẽ trả 2 USD + 1 USD = 3 USD.
    • Ví dụ: chuyến đi 1 phút; chuyến đi 1 phút 45 giây
  • x số phút, trong đó x lớn hơn hoặc bằng 2: 3 USD + ((2 USD + 1 USD) * (x – 2 + 1))
    • Nếu hành trình dài hơn hoặc bằng 2 phút, người dùng sẽ trả 3 USD cho phần hành trình dưới 2 phút và (1 USD [tiếp tục từ mục đầu tiên trong danh sách per_min_pricing] + 2 USD [mục thứ hai trong danh sách per_min_pricing]) cho mỗi phút sau và bao gồm cả 2 phút.
    • Ví dụ:
      • Chuyến đi 2 phút có giá 3 USD + (2 USD + 1 USD) = 6 USD
      • Chuyến đi dài 2 phút 30 giây có giá là 3 USD + (2 USD + 1 USD) = 6 USD
      • Chuyến đi 3 phút có giá 3 USD + ((2 USD + 1 USD) * 2) = 9 USD
      • Chuyến đi 10 phút có giá là 3 đô la Mỹ + ((2 đô la Mỹ + 1 đô la Mỹ) * 9) = 30 đô la Mỹ
{
  "plans": {
    "plan_id": "plan1",
    "currency": "USD",
    "price": 2,
    "per_min_pricing": [
      {
          "interval": 1,
          "rate": 1,
          "start": 1
      },
      {
          "interval": 1,
          "rate": 2,
          "start": 2
      }
    ],
  }
}

Ví dụ 2 cho system_pricing_plans.json

Trong ví dụ này, chúng tôi minh hoạ một mẫu mã cho gói giá được tính theo cả phút và ki-lô-mét:

  • Cụ thể, người dùng cuối sẽ bị tính phí 0,25 CAD/km cũng như 0,5 CAD/phút.
  • Cả hai tốc độ này đều diễn ra đồng thời và không phụ thuộc vào nhau.
  • Do đó, một chuyến đi dài 1 km trong 10 phút sẽ có giá 9 CAD. Sau đây là thông tin chi tiết về chi phí:
    • 3 đô la, giá cơ sở
    • 0,25 USD * 2, tính phí một lần khi bắt đầu chuyến đi và một lần khi đến mốc 1 km.
    • 0,5 * 11, tính phí một lần vào đầu mỗi phút. Bắt đầu tính phí từ 0 giây, với khoảng thời gian cuối cùng được tính phí là 10 phút.
{
  "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
    }]
  }
}

Bắt buộc có điều kiện: geofencing_zones.json (Hệ thống có trạm sạc và không có trạm sạc)

Tham khảo quy cách GBFS nếu cần.

Nguồn cấp dữ liệu này xác định dữ liệu hàng rào địa lý cho các phương tiện độc lập. Dữ liệu về hàng rào địa lý bao gồm ranh giới địa lý chỉ định nơi xe được phép bắt đầu và kết thúc chuyến đi, cùng với tốc độ mà xe có thể đi. Tốc độ này là tốc độ tối đa của xe hoặc giới hạn tốc độ của đường mà xe đang đi, tuỳ theo tốc độ nào thấp hơn. Người lái xe phải tuân thủ luật pháp và pháp lệnh địa phương.

Chúng tôi sử dụng dữ liệu này để khi người dùng tìm kiếm một tuyến đường nhất định, nếu điểm cuối của chuyến đi nằm ngoài hàng rào địa lý cụ thể, thì kết quả về phương tiện siêu nhỏ sẽ bị lọc. Nếu bạn không cung cấp hàng rào địa lý, Google sẽ coi dịch vụ này như thể không có hạn chế về ranh giới.

Tên trường Loại Yêu cầu Mô tả
geofencing_zones Đối tượng Bắt buộc Đối tượng FeatureCollection như được mô tả trong IETF RFC 7946 là một đối tượng có trường, có tên là features. Giá trị của features là một mảng JSON. Mỗi phần tử của mảng JSON là một đối tượng Feature.

Mỗi vùng có hàng rào địa lý, các quy tắc và thuộc tính liên quan, cũng như định nghĩa về FeatureCollection được chỉ định ở đây trong phần định nghĩa nguồn cấp dữ liệu geofencing_zones.json.
geofencing_zones.type Chuỗi Bắt buộc Đặt thành FeatureCollection như mô tả trong IETF RFC 7946.
geofencing_zones.features Mảng Bắt buộc Một mảng JSON, trong đó mỗi phần tử của mảng JSON là một đối tượng Feature.
geofencing_zones.features[].type Chuỗi Bắt buộc Đặt thành Feature như mô tả trong IETF RFC 7946.
geofencing_zones.features[].geometry GeoJSON Multipolygon Bắt buộc Một GeoJSON Multipolygon mô tả những nơi không thể bắt đầu, kết thúc, đi qua chuyến đi, ngoài ra còn có những hạn chế khác. Cách sắp xếp các điểm theo chiều kim đồng hồ sẽ xác định vùng được bao quanh bởi đa giác, trong khi thứ tự ngược chiều kim đồng hồ sẽ xác định vùng bên ngoài đa giác. Để biết thêm thông tin về vấn đề này, hãy tham khảo quy tắc bàn tay phải.
geofencing_zones.features[].properties Đối tượng Bắt buộc Một đối tượng xác định các khoản trợ cấp và hạn chế đi lại.
geofencing_zones.features[].properties.rules Mảng Không bắt buộc Một mảng các đối tượng, trong đó mỗi đối tượng xác định một và chỉ một quy tắc. Nếu hai hoặc nhiều quy tắc trùng lặp, xung đột hoặc xung đột theo cách nào đó, thì quy tắc được xác định sớm nhất theo thứ tự của tệp JSON sẽ được ưu tiên.
geofencing_zones.features[].properties.rules[].vehicle_type_id Mảng Không bắt buộc Một mảng gồm mã loại xe, trong đó mỗi phần tử là một vehicle_type_id mà mọi quy định hạn chế phải được áp dụng. Nếu bạn không chỉ định vehicle_type_id, thì các quy tắc hạn chế sẽ áp dụng cho tất cả các loại xe.
geofencing_zones.features[].properties.rules[].ride_allowed Boolean Bắt buộc Liệu chuyến đi xe đạp "không có trạm sạc" độc lập có thể bắt đầu và kết thúc trong khu vực hay không, như sau:
  • Nếu chuyến đi xe đạp không cần gắn vào giá đỡ có thể bắt đầu và kết thúc trong khu vực, hãy đặt thành true.
  • Nếu chuyến đạp xe không có trạm sạc không thể bắt đầu và kết thúc trong khu vực, hãy đặt thành false.

Sau đây là một ví dụ về 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]
      ]]]
    }
  }]
}

Bắt buộc: station_information.json (Hệ thống có trạm sạc)

Tham khảo quy cách GBFS nếu cần.

Nguồn cấp dữ liệu này xác định thông tin chung về các trạm xe đạp công cộng.

Tên trường Loại Yêu cầu Mô tả
stations Mảng Bắt buộc Một mảng gồm các đối tượng, trong đó mỗi đối tượng xác định một và chỉ một trạm sạc.
stations[].station_id Chuỗi Bắt buộc Giá trị nhận dạng của trạm sạc.
stations[].name Chuỗi Bắt buộc Tên công khai của trạm sạc bằng ngôn ngữ địa phương của thành phố nơi trạm sạc đặt tại. name phải tuân thủ những gì được sử dụng trên biển báo tại nhà ga (nếu có) hoặc phải phản ánh vị trí của nhà ga thông qua việc sử dụng đường giao nhau hoặc địa danh địa phương. Không sử dụng từ viết tắt như "St." cho "Street" (Đường) trừ phi từ này được dùng rõ ràng trong biển báo và name phải có cả chữ hoa và chữ thường theo quy ước địa phương về cách viết hoa tên địa điểm, chứ không phải viết hoa toàn bộ.
stations[].lat Vĩ độ Bắt buộc Vĩ độ WGS 84 của trạm, ở định dạng độ thập phân.
stations[].lon Kinh độ Bắt buộc Kinh độ WGS 84 của trạm, ở định dạng độ thập phân.
stations[].capacity Số nguyên không âm Không bắt buộc Một số nguyên không âm biểu thị tổng số điểm sạc đã được lắp đặt tại trạm sạc, cả điểm sạc đang hoạt động và không hoạt động.
stations[].rental_uris Đối tượng Bắt buộc

Một đối tượng JSON chứa URI cho thuê cho Android, iOS và web trong các trường tương ứng.

Nếu bạn chỉ định các URI này, chúng sẽ ghi đè các đường liên kết sâu mặc định được đặt khi nhà cung cấp tham gia.
stations[].rental_uris.android URI Bắt buộc có điều kiện

Một URI có thể được truyền đến ứng dụng Android bằng ý định android.intent.action.VIEW của Android để hỗ trợ Đường liên kết sâu của Android. rental_uris được cung cấp phải là Đường liên kết đến ứng dụng Android để ứng dụng xem không cần quản lý thủ công việc chuyển hướng người dùng đến cửa hàng ứng dụng trong trường hợp người dùng chưa cài đặt ứng dụng của nhà cung cấp.

URI này phải là một đường liên kết sâu dành riêng cho từng trạm sạc, chứ không phải là một trang cho thuê chung có thông tin cho nhiều trạm sạc. Đường liên kết sâu phải đưa người dùng đến thẳng đài phát mà không cần đến lời nhắc, trang xen kẽ hay thao tác đăng nhập. Đảm bảo rằng người dùng có thể thấy trạm sạc ngay cả khi họ chưa từng mở ứng dụng.

URI không nhất thiết phải bao gồm station_id cho trạm sạc, miễn là đối tác có những cách khác để xác định trạm sạc tương ứng. Ví dụ: ứng dụng cho thuê có thể sử dụng các giá trị nhận dạng khác trong URI để xác định duy nhất trạm sạc.

Nếu đối tác có ứng dụng cho thuê trên Android, thì bạn phải điền trường này.

Ví dụ về Đường liên kết trong ứng dụng Android:

https://www.example.com/app?sid=1234567890&platform=android
stations[].rental_uris.ios URI Bắt buộc có điều kiện

Một URI có thể dùng trên iOS để chạy ứng dụng cho thuê của đài. Để biết thêm thông tin về vấn đề này, hãy tham khảo bài viết của Apple về các lược đồ URL tuỳ chỉnh của iOS. rental_uris được cung cấp phải là Đường liên kết phổ quát trên iOS để ứng dụng xem không cần quản lý thủ công việc chuyển hướng người dùng đến cửa hàng ứng dụng trong trường hợp người dùng chưa cài đặt ứng dụng của nhà cung cấp.

URI này phải là một đường liên kết sâu dành riêng cho từng trạm sạc, chứ không phải là một trang cho thuê chung có thông tin cho nhiều trạm sạc. Đường liên kết sâu phải đưa người dùng đến thẳng đài phát mà không cần đến lời nhắc, trang xen kẽ hay thao tác đăng nhập. Đảm bảo rằng người dùng có thể thấy trạm sạc ngay cả khi họ chưa từng mở ứng dụng.

URI không nhất thiết phải chứa station_id cho trạm sạc. Ứng dụng cho thuê có thể sử dụng các giá trị nhận dạng khác trong URI để xác định riêng biệt trạm sạc.

Nếu đối tác có ứng dụng cho thuê trên iOS, thì bạn phải điền trường này.

Ví dụ về Đường liên kết phổ quát trên iOS:

https://www.example.com/app?sid=1234567890&platform=ios
stations[].rental_uris.web URL Không bắt buộc

URL mà trình duyệt web có thể dùng để cho biết thêm thông tin về cách thuê xe tại trạm sạc này.

URL này phải là một đường liên kết sâu dành riêng cho từng trạm sạc, chứ không phải là một trang cho thuê chung có thông tin về nhiều trạm sạc. Đường liên kết sâu phải đưa người dùng đến thẳng đài phát mà không cần đến lời nhắc, trang xen kẽ hay thao tác đăng nhập. Đảm bảo rằng người dùng có thể xem nhà ga ngay cả khi họ chưa từng mở ứng dụng.

Bạn không nhất thiết phải thêm station_id vào URL của đài truyền hình hoặc tuân theo các quy ước ngữ nghĩa của URL cho thuê đối với Android hoặc iOS. Ứng dụng cho thuê có thể sử dụng các giá trị nhận dạng khác trong URL để xác định riêng biệt trạm sạc.

Nếu bạn không đặt trường này, tức là trình duyệt web không hỗ trợ đường liên kết sâu.

Giá trị mẫu:

https://www.example.com/app?sid=1234567890

Sau đây là một ví dụ về 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"
    }
  },
]

Bắt buộc: station_status.json (Hệ thống có trạm sạc)

Tham khảo quy cách GBFS nếu cần.

Nguồn cấp dữ liệu này xác định trạng thái hiện tại và mới nhất của các trạm xe đạp dùng chung công cộng.

Tên trường Loại Yêu cầu Mô tả
stations Mảng Bắt buộc Một mảng gồm các đối tượng, trong đó mỗi đối tượng xác định một và chỉ một trạm sạc.
stations[].station_id Chuỗi Bắt buộc Giá trị nhận dạng của trạm sạc.
stations[].num_bikes_available Số nguyên không âm Bắt buộc

Một số nguyên không âm biểu thị số lượng xe đạp hoạt động đang có tại trạm và có thể được cho thuê.

Để xác định xem trạm có đang cho thuê xe đạp hay không, bạn phải kiểm tra trường is_renting của trạm và tìm giá trị Boolean là true.
stations[].vehicle_types_available Mảng Không bắt buộc

Một mảng các đối tượng xác định tổng số xe, được phân loại theo từng loại xe có tại một trạm sạc. Mỗi đối tượng mô hình hoá tổng số phương tiện cho loại phương tiện được liên kết. Tổng số lượng xe của mỗi đối tượng này phải cộng lại bằng giá trị được chỉ định trong trường num_bikes_available.
stations[].vehicle_types_available[].vehicle_type_id Mã nhận dạng Bắt buộc

vehicle_type_id của từng loại xe có tại trạm sạc như mô tả trong vehicle_types.json.
stations[].vehicle_types_available[].count Số nguyên không âm Bắt buộc

Tổng số xe có sẵn cho vehicle_type_id tương ứng tại trạm sạc như được xác định trong vehicle_types.json.
stations[].num_docks_available Số nguyên không âm Bắt buộc có điều kiện

Đây là trường bắt buộc, trừ phi trạm sạc có công suất sạc không giới hạn. Ví dụ: trạm ảo có số lượng cổng sạc không giới hạn và bạn không bắt buộc phải điền trường này.

Một số nguyên không âm biểu thị tổng số bến sạc hoạt động tại trạm sạc có thể chấp nhận xe trả lại.

Để xác định xem trạm sạc hiện có chấp nhận xe đạp trả lại hay không, bạn phải kiểm tra trường is_returning của trạm sạc và tìm giá trị Boolean true.
stations[].is_installed Boolean Bắt buộc

Giá trị Boolean cho biết liệu trạm sạc có đang được lắp đặt trên đường phố hay không.

Nếu trạm sạc được lắp đặt trên đường phố, hãy đặt thành true.

Nếu trạm sạc không được lắp đặt trên đường phố, hãy đặt thành false.
stations[].is_renting Boolean Bắt buộc

Một giá trị Boolean cho biết liệu trạm hiện có cho thuê xe đạp hay không.

Nếu trạm hiện đang cho thuê xe đạp, hãy đặt thành true. Ngay cả khi trạm sạc không có xe, nếu bạn đặt cho phép thuê thì is_renting sẽ được đặt thành true.

Nếu trạm hiện không cho thuê xe đạp, hãy đặt thành false.
stations[].is_returning Boolean Bắt buộc

Một giá trị Boolean cho biết liệu trạm hiện có chấp nhận trả xe đạp hay không.

Nếu trạm hiện chấp nhận trả xe đạp, hãy đặt thành true. Ngay cả khi trạm sạc đã đầy nhưng cho phép trả lại nếu chưa đầy, is_returning sẽ được đặt thành true.

Nếu trạm sạc hiện không chấp nhận trả xe đạp, hãy đặt thành false.

Sau đây là một ví dụ về 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
        },
]