Incorporate Best Practice Recommendations #271

mplsmitch · 2020-10-12T15:41:56Z

This proposal incorporates best practice recommendations into the specification. These recommendations have been developed over the past two years based on community feedback.

The objectives of incorporating GBFS Best Practices recommendations into the specification are:

To improve end-user customer experience in shared mobility apps
Support broad data interoperability to make it easier for software developers to deploy and scale applications, products, and services
Facilitate the use of GBFS in various application categories (beyond its original focus on trip planning)

These additions touch many areas of the specification but generally fall into the following three categories:

Clarifying the intended use of various GBFS endpoints and fields.
Ensuring uninterrupted access to GBFS data.
Improving the overall quality and completeness of GBFS feeds.

This proposal is intended to be non-breaking. There will be a second, smaller proposal following this one containing breaking changes.

Adds best practices recommendations. Cleans up typos. Fixes broken anchors.

updates free_bike_status definition

Adds info on latency requirements, formatting changes

nighthawk

Minor suggestions from proof reading.

gbfs.md

Co-authored-by: Adrian Schoenig <adrian@schoenig.me>

restores vehicle_capacity, minor edits

fixes borken links and minor typos

evansiroky · 2020-10-23T00:54:30Z

gbfs.md

@@ -267,7 +331,7 @@ Field Name | Required | Type | Defines

 ### vehicle_types.json *(added in v2.1-RC)*

-The following fields are all attributes within the main "data" object for this feed.
+This file should be published by systems offering multiple vehicle types for rental, for example pedal bikes and ebikes. <br/>The following fields are all attributes within the main "data" object for this feed.


I think it'd be good to add stronger wording here to reflect the requirement of this file in these types of systems. Maybe something like:

This file must be published...

@evansiroky I'm reluctant to make vehicle_types.json a requirement when this is intended to be a non-breaking PR. While requiring it may not break down stream apps it seems like a significant change for producers. Currently it's conditionally required of systems who publish vehicle type data in free_bike_status.json. I think we should revisit how it's defined in v3.0.

I'm confused. In the Files section, it says that this file is conditionally required already. Seems like that same language ought to be used here to be consistent.

I've added the language from the Files section-

As it's currently defined under Files, systems publishing vehicle type information in free_bike_status MUST publish vehicle_types.json. If they are not including vehicle type information in free_bike_status they would be exempted from that requirement regardless of the types of vehicles offered. This says that for those that operate multiple types of vehicles, publishing vehicle_types.json is something they SHOULD do. If that's not adequate, we could redefine vehicle_types.json in v3.0 to require it of systems operating multiple types of vehicles

gbfs.md

kanagy · 2020-10-23T05:42:25Z

gbfs.md

-\-&nbsp;`num_docks_available` | Conditionally required <br/>*(as of v2.0)* | Non-negative integer | Required except for stations that have unlimited docking capacity (e.g. virtual stations) *(as of v2.0)*. Number of functional docks physically at the station. To know if the docks are accepting vehicle returns, see `is_returning`.
-\- `vehicle_docks_available` <br/>*(added in v2.1-RC)* | Conditionally Required | Array | This field is required in feeds where the [vehicle_types.json](#vehicle_typesjson) is defined and where certain docks are only able to accept certain vehicle types. If every dock at the station is able to accept any vehicle type, then this field is not required. This field's value is an array of objects. Each of these objects is used to model the number of docks available for certain vehicle types. The total number of docks from each of these objects should add up to match the value specified in the `num_docks_available` field.
+\-&nbsp;`station_id` | Yes | ID | Identifier of a station. See [station_information.json](#station_informationjson).
+\-&nbsp;`num_bikes_available` | Yes | Non-negative integer | The total number of vehicles of all types that are currently available and offered for rental at the station. If the `is_renting` boolean is set to`false` this number should be zero.


Should this be conditionally required for valet stations, similar to num_docks_available?

That's a good question, what I don't understand is if there were a valet station with an unlimited supply of vehicles, how would the operator indicate that there are any bikes available without using this field? In practice I don't think it matters that much because where i've seen valet service, the operator uses the station to initiate the rentals so it's constantly being refilled to maintain the value in num_bikes_available

gbfs.md

minor edits, updates stations_status to align with changes in #261

gbfs.md

fix typo

Change num_bikes_available and num_docks_available definitions to better align with v2.0

Updates vehicle_types.json definition to reflect changes in 2.1RC2

mplsmitch · 2020-11-02T15:17:03Z

I hereby call a vote on this proposal. Voting will be open for 7 full calendar days until 11:59PM UTC on Monday, November 9th.
Please vote for or against the proposal, and include the organization for which you are voting in your comment.

Additional detail in description of vehicle_types.json

kanagy

Would you be able to also update the system_pricing_plans documentation to clarify start/end interval points in pricing? When I looked at it recently it wasn't clear whether the start/end points in pricing are exclusive or inclusive, and exactly at which point the price increases.

E.g. the start documentation says "Number of kilometers that have to elapse before this segment starts applying." Does this mean that if start=1 and trip takes 1 min, we don't charge the user, but if the trip is taking 1.01 min we would charge the user? Similar confusion for the end field.

kanagy · 2020-11-03T06:42:05Z

gbfs.md

@@ -501,7 +564,7 @@ Example:
 ```

 ### system_hours.json
-Describes the system hours of operation.
+This optional file is used to describe hours and days of operation when vehicles are available for rental. If `system_hours.json` is not published it indicates that vehicles are available for rental 24 hours a day, 7 days a week.


I think more clarification is needed that: if a system is outside of hours of operation, it should have no vehicles available in the realtime feeds (i.e. it should set num_bikes_available=0 and have no vehicles in free_bike_status.json). I'm not sure that is mentioned anywhere. The last sentence here makes it sound like consumers need to ingest system_hours just to determine if current real-time availability is outside of hours of operation.

if a system is outside of hours of operation, it should have no vehicles available in the realtime feeds (i.e. it should set num_bikes_available=0 and have no vehicles in free_bike_status.json).

The definition of num_bikes_available was changed (discussion in #94, PR #195 )to say just the opposite of this. During off hours num_bikes_available now remains constant so someone trying to plan a trip at 6:45 can see how many vehicles are going to be available at 7:00 when the system opens. Same should be true for free_bike_status. In a station based system the operator could set is_renting to false in station_status during the time when the system is closed but there's no equivalent in free_bike_status so you would need to ingest system_hours.

Would you be able to also update the system_pricing_plans documentation to clarify start/end interval points in pricing?

start and end definitions have been updated in pricing

I see. I don't like that the realtime part of the spec does not reflect the realtime rental availability and consumers have to double-check with another mostly static feed, but I do respect conversation in #94. Would it make sense to add guidance to is_renting on whether this should be set to false outside of hours of operation? Currently the description seems to point towards it: "temporarily taken out of service".

Adds additional detail to pricing start and end fields

kanagy · 2020-11-03T22:39:52Z

gbfs.md

 &emsp;&emsp;\-&nbsp;`rate` <br/>*(added in v2.1-RC2)* | Yes | Float | Rate that is charged for each kilometer `interval` after the `start`. Can be a negative number, which indicates that the traveller will receive a discount.
 &emsp;&emsp;\-&nbsp;`interval` <br/>*(added in v2.1-RC2)* | Yes | Non-Negative Integer | Interval in kilometers at which the `rate` of this segment is either reapplied indefinitely, or if defined, up until (but not including) `end` kilometer.<br /><br />An interval of 0 indicates the rate is only charged once.
-&emsp;&emsp;\-&nbsp; `end` <br/>*(added in v2.1-RC2)* | Optional | Non-Negative Integer | The kilometer at which the rate will no longer apply.<br /><br /> If this field is empty, the price issued for this segment is charged until the trip ends, in addition to following segments.
+&emsp;&emsp;\-&nbsp; `end` <br/>*(added in v2.1-RC2)* | Optional | Non-Negative Integer | The kilometer at which the rate will no longer apply *(exclusive)* e.g. if `end` is `20` the rate no longer applies at 20.00 km.<br /><br /> If this field is empty, the price issued for this segment is charged until the trip ends, in addition to following segments.


Sorry, this still doesn't make the rate function clear to me. It seems neither the start or the end minute/kilometer is included in the range. Assume per_min_pricing:
{start: 1, end: 3, rate: 1}, {start: 3, end: 4, rate: 0.5}

Is this how much trips would cost at these times:

1 min: 0

1 min 1 second to 2 min: 1

2 min: 1

2 min 1 second to 3 min: 2

3 min: 2

3 min 1 second: 2.5
?

Because start is inclusive, your example {start: 1, end: 3, rate: 1}, {start: 3, end: 4, rate: 0.5} assuming interval is 1 would result in:

0-59 sec: 0
1 min: 1
1 min 1 second to 1 min 59 sec: 1
2 min: 2
2 min 1 second to 2 min 59 sec: 2
3 min: 3
3 min 1 second to 3 min 59 sec: 3.5
4 min 3.5

To set per min pricing you would use { start: 0, interval: 1, rate: 1 } which would result in:
0-59 sec: 1
1 min to 1 min 59 sec: 2
2 min to 2 min 59 sec: 3

Would it make sense to add guidance to is_renting on whether this should be set to false outside of hours of operation?

added "Field should be set to false during hours or days when the system is not offering vehicles for rent"

The description for start says: "kilometers (inclusive) that have to elapse before this segment starts applying". Note the "before" and "elapse" bits.

I.e. if start=1, this reads to me that 1 kilometer (inclusive) has to elapse before the segment starts applying. I.e. we have to get past the 1km mark. If it said exclusive, it would make more sense to me. But I would suggest chancing this sentence completely. How about: "The kilometer at which this segment rate starts being charged (inclusive)."

kanagy · 2020-11-03T22:45:51Z

gbfs.md

@@ -501,7 +564,7 @@ Example:
 ```

 ### system_hours.json
-Describes the system hours of operation.
+This optional file is used to describe hours and days of operation when vehicles are available for rental. If `system_hours.json` is not published it indicates that vehicles are available for rental 24 hours a day, 7 days a week.


I see. I don't like that the realtime part of the spec does not reflect the realtime rental availability and consumers have to double-check with another mostly static feed, but I do respect conversation in #94. Would it make sense to add guidance to is_renting on whether this should be set to false outside of hours of operation? Currently the description seems to point towards it: "temporarily taken out of service".

updates guidance on is_renting

fix typo

update to clarify pricing start definition

kanagy · 2020-11-08T22:36:36Z

Thanks for documenting the best practices. Voting +1 from Google Maps

cmonagle · 2020-11-09T14:33:59Z

+1 on behalf of Transit.

nighthawk · 2020-11-09T15:02:01Z

+1 from SkedGo.

evansiroky · 2020-11-09T18:15:01Z

+1 from IBI Group

mplsmitch · 2020-11-10T17:09:01Z

This vote has been extended until 11:59PM UTC on Thursday, November 12th. Please weigh in for or against the proposal, and include the organization for which you are voting in your comment.

jayjonsson · 2020-11-10T23:02:32Z

+1 from Lime

bhandzo · 2020-11-11T00:41:00Z

+1 from Bird.

sfaubert1 · 2020-11-11T16:53:13Z

+1 from PBSC

mplsmitch · 2020-11-13T15:38:29Z

This vote is now closed - and it passes

Votes in favor:
Google Maps (consumer)
Transit (consumer)
IBI (consumer)
Lime (producer)
Bird (producer)
PBSC (producer)
SkedGo (consumer)

There we no votes against

Mitch Vars added 2 commits October 9, 2020 09:33

Update gbfs.md

9524a74

Adds best practices recommendations. Cleans up typos. Fixes broken anchors.

Update gbfs.md

6c3cda9

mplsmitch added the proposal:nonbreaking label Oct 12, 2020

Mitch Vars added 3 commits October 16, 2020 11:01

Update gbfs.md

7895782

updates free_bike_status definition

Update gbfs.md

72d14d2

Adds info on latency requirements, formatting changes

Merge branch 'master' into best-practices-nb

e37000e

nighthawk reviewed Oct 20, 2020

View reviewed changes

gbfs.md Show resolved Hide resolved

gbfs.md Outdated Show resolved Hide resolved

gbfs.md Outdated Show resolved Hide resolved

gbfs.md Outdated Show resolved Hide resolved

gbfs.md Outdated Show resolved Hide resolved

gbfs.md Show resolved Hide resolved

Mitch Vars and others added 3 commits October 20, 2020 08:15

Apply suggestions from code review

1b708fd

Co-authored-by: Adrian Schoenig <adrian@schoenig.me>

Update gbfs.md

e057228

restores vehicle_capacity, minor edits

Update gbfs.md

947210c

fixes borken links and minor typos

This was referenced Oct 21, 2020

Multiple auto-discovery feeds in website header #256

Closed

When to consider data from a feed outdated? #232

Closed

evansiroky reviewed Oct 23, 2020

View reviewed changes

gbfs.md Outdated Show resolved Hide resolved

evansiroky reviewed Oct 23, 2020

View reviewed changes

gbfs.md Outdated Show resolved Hide resolved

kanagy reviewed Oct 23, 2020

View reviewed changes

Update gbfs.md

6c4aac6

minor edits, updates stations_status to align with changes in #261

evansiroky reviewed Oct 27, 2020

View reviewed changes

gbfs.md Outdated Show resolved Hide resolved

Mitch Vars added 3 commits October 27, 2020 07:58

Update gbfs.md

9a86bc7

fix typo

Update gbfs.md

6974394

Change num_bikes_available and num_docks_available definitions to better align with v2.0

Update gbfs.md

ba9144b

Updates vehicle_types.json definition to reflect changes in 2.1RC2

mplsmitch added the Vote open label Nov 2, 2020

Update gbfs.md

faf2b69

Additional detail in description of vehicle_types.json

kanagy reviewed Nov 3, 2020

View reviewed changes

Update gbfs.md

fe01d63

Adds additional detail to pricing start and end fields

kanagy reviewed Nov 3, 2020

View reviewed changes

Mitch Vars added 3 commits November 4, 2020 13:35

Update gbfs.md

2fba7cd

updates guidance on is_renting

Update gbfs.md

9f61e31

fix typo

Update gbfs.md

e732879

update to clarify pricing start definition

Update gbfs.md

eefbdf1

mplsmitch added the Vote Closing Soon label Nov 9, 2020

mplsmitch removed Vote Closing Soon proposal:nonbreaking Vote open labels Nov 13, 2020

mplsmitch merged commit 22a116c into master Nov 13, 2020

mplsmitch mentioned this pull request Jan 13, 2021

system_id and aggregated feeds #286

Closed

mplsmitch deleted the best-practices-nb branch March 18, 2021 18:33

josee-sabourin added gbfs.md Vote Passed labels Jun 8, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Incorporate Best Practice Recommendations #271

Incorporate Best Practice Recommendations #271

mplsmitch commented Oct 12, 2020

nighthawk left a comment

evansiroky Oct 23, 2020

mplsmitch Oct 29, 2020

evansiroky Nov 2, 2020

mplsmitch Nov 2, 2020

kanagy Oct 23, 2020

mplsmitch Oct 23, 2020

mplsmitch commented Nov 2, 2020

kanagy left a comment

kanagy Nov 3, 2020

mplsmitch Nov 3, 2020

mplsmitch Nov 3, 2020

kanagy Nov 3, 2020

kanagy Nov 3, 2020

mplsmitch Nov 4, 2020

mplsmitch Nov 4, 2020

kanagy Nov 4, 2020

kanagy Nov 3, 2020

kanagy commented Nov 8, 2020

cmonagle commented Nov 9, 2020

nighthawk commented Nov 9, 2020

evansiroky commented Nov 9, 2020

mplsmitch commented Nov 10, 2020

jayjonsson commented Nov 10, 2020

bhandzo commented Nov 11, 2020

sfaubert1 commented Nov 11, 2020

mplsmitch commented Nov 13, 2020 •

edited

Loading

Incorporate Best Practice Recommendations #271

Incorporate Best Practice Recommendations #271

Conversation

mplsmitch commented Oct 12, 2020

nighthawk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mplsmitch commented Nov 2, 2020

kanagy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kanagy commented Nov 8, 2020

cmonagle commented Nov 9, 2020

nighthawk commented Nov 9, 2020

evansiroky commented Nov 9, 2020

mplsmitch commented Nov 10, 2020

jayjonsson commented Nov 10, 2020

bhandzo commented Nov 11, 2020

sfaubert1 commented Nov 11, 2020

mplsmitch commented Nov 13, 2020 • edited Loading

mplsmitch commented Nov 13, 2020 •

edited

Loading