Unclear definition of GBFS `num_bikes_available` - `is_renting` is ignored in OTP

[barbeau]

There is currently a discussion going on in the General Bikeshare Feed Spec. (GTFS) forum: https://github.com/NABSA/gbfs/issues/94

...surrounding the definition of station_status.num_bikes_available.

Some of the original authors of GBFS are saying that num_bikes_available was intended to be used in conjunction with the is_renting field (let's call this Interpretation A) - in other words, num_bikes_available could be 5 but if is_renting is false then no bikes should be shown as "rentable" to the end user, This definition isn't mentioned explicitly anywhere in the spec.

My interpretation of GBFS (Interpretation B) is that if is_renting is false, num_bikes_available should always be 0. In other words, you don't need to check the value of is_renting at all, and showing num_bikes_available to the end user will always result in showing the user the number of bikes rentable right now.

Looking at GbfsBikeRentalDataSource it looks like OTP uses Interpretation B as well - the is_renting field is not consumed.

It is being proposed in GBFS issue https://github.com/NABSA/gbfs/issues/94 to simply clarify the definition of num_bikes_available to be Interpretation A. However, this will be a breaking change to any producer/consumer system that's implemented Interpretation B (including OTP and downstream systems that use OTP Bikeshare API).

@demory @fpurcell Do you know which interpretation Biketown uses in their GBFS feed?

Is there anyone else here using OTP to consume GBFS that could say which interpretation their GBFS producer is using?

I'd also encourage everyone to weigh in on GBFS issue https://github.com/NABSA/gbfs/issues/94 with your interpretation, or the impact the adoption of Interpretation A would have on your systems.

Expected behavior

According to changes proposed in discussion in https://github.com/NABSA/gbfs/issues/94 (i.e., Interpretation A), GBFS consumers should check is_renting before showing num_bikes_available to the end user as the number of bikes currently available to rent.

Observed behavior

Looking at GbfsBikeRentalDataSource OTP does not consume the GBFS is_renting field, and as a result the end user is shown num_bikes_available as the number of bikes available to rent.

Under Interpretation B this is correct behavior, but not under Interpretation A.

To meet Interpretation A requirements, OTP would need to be modified to consume the GBFS is_renting field and developers must modify/notify any downstream clients of the OTP API of the change in definition. Under Interpretation A, clients would need to change to the following behavior - if is_renting is true, then num_bikes_available can be shown to end users as the number of bikes currently rentable. If is_renting is false, then no bikes are currently rentable at the station (regardless of the value of num_bikes_available).

Version of OTP used (exact commit hash or JAR name)

OTP master branch at 3a9738e1aef4a23b0d30710b041bc7477451eaf1 (1.3.0-SNAPSHOT)

Data sets in use (links to GTFS and OSM PBF files)

N/A

Command line used to start OTP

N/A

Router config and graph build config JSON

N/A

Steps to reproduce the problem

N/A

[barbeau]

From https://github.com/NABSA/gbfs/issues/94#issuecomment-385105167:

38 systems are working with BCYCLE technologies, we found that 14 of these systems are mantaining the num of bikes and docks even when the renting and returning flags are "0", we are not sure about the other 24 but we can asume that are following the same logic. ... Other systems that we found that are mantaining the values of bikes and docks available are Citibike NewYork, Divvybikes Chicago and Socialbicycles Phoenix.

So, assuming this analysis is correct, the current OTP GBFS consuming code will show that there are bikes available to rent for these systems that aren't actually available to rent (i.e., is_renting is false).

[fpurcell]

Hey Sean,

I'll leave it up to @demory to confirm / explain his OTP implementation. FWIW, I read the spec with interpretation A. I see is_renting=false as a flag overriding the num_bikes_available values.

BTW, I'm consuming GBFS to show BIKETOWN bike racks on https://maps.trimet.org/?tool=bikeshare ... I only load the data once per day (nightly) right now. And I won't show a rack (for 24 hours) when is_renting == false OR is_returning == false (https://github.com/OpenTransitTools/gbfsdb/blob/master/ott/gbfsdb/stations.py#L20). I don't look at bike levels at the stop when composing the list of racks to be shown, since for a map overlay of rack locations, that's meaningless.

Later, Frank

[leonardehrenfried]

I think this was fixed in #3610. Can someone confirm?

[hannesj]

Yes, is_renting is now blocking rentals, and num_bikes_available is ignored in routing if a station is not renting. It is however still exposed in the APIs.