Number of bikes and docks available during non service hours or out of service stations

[Noe-Santana]

Hello everyone.

There are a some systems that doesn't work the whole day, in these cases, What should be the behaviour of the num_bikes_available during the non service hours?

There are two values that indicate if a station is renting or receiving bikes, additionally, The number of bikes and docks should change to "0" on each case?, I can see that not all the systems are managing these values the same way so I would like to find a standarization.

In our experience, mantain the value of bikes and docks available at the station as an independent value from the renting and returning flags can be much more valuable for analisys and developing purposes, also, as an end user is very functional to know where the bikes are, it allows the user to plan where to go and take a bike at the very first hours of service, ultimately, there are a lot of options like color, size, shape, symbols, legends, etc. to represent the functional status and the occupation of a station at the same time.

[mplsmitch]

During non-service hours num_bikes_available would be "0". This probably wouldn't be true of num_docks_available since most systems allow returns outside of business hours.

[Noe-Santana]

Thanks for your response Mitch.

Doo you think that the "num_bikes_available" on the feed should change when there is a "is_renting" flag?, if a developer of an end user tool based on the GBFS decides that it should work the way you propose it still possible by using this flag.

On the other hand, if there is a purpose of analysis of the distribution of the bikes, having the numbers of bikes at the stations at all time is something indispensable, in fact is a number that tends to be more accurate when the system is not in service for the end users.

The value always available can reflect the work of the operators at night, either for the community interested on bikeshare systems or for the regulators of the service like in some cases the goverment.

[barbeau]

IMHO num_bikes_available should definitely be the the number of bikes available to rent right now - consumers shouldn't need to check the is_renting flag to see what this field means. A different default interpretation based on is_renting would break existing consumers. The GBFS Guiding Principles say:

GBFS is a specification for real-time or semi-real-time, read-only data. The spec is not intended for historical or archival data such as trip records. The spec is about public information intended for bikeshare users.

While being able to analyze service would be nice, IMHO this needs to be in separate fields dedicated to this concept, if they should be in GBFS at all.

[jcn]

Doesn't the consumer always have to check is_renting - otherwise, what's the point of it? The explanation of that field is: "is the station currently renting bikes (even if the station is empty, if it is set to allow rentals this value should be 1)" The implication of the example being that if the station is allowing rentals, it's true, even if it's empty. It seems like the opposite would also be true - if this field is 0 then it doesn't matter how many bikes are available - the station should be marked as not allowing rentals. It seems like num_bikes_available might be misnamed a little, but my impression was always that this number was "how many physical non-broken bikes are there at the station that I could take out, *if the station is allowing rentals*"

[dsgermain]

I always interpreted is_renting as something to help UI designers tell users that a station is explicitely not allowing rentals, so that users don't walk towards it thinking that a bike might arrive in the meantime.

It is different from the case of having 0 bikes alone, as that might be a transient value because rebalancing hasn't taken place yet, or a bike is about to be returned by a user.

For me, if is_renting is false, num_bikes_available should always be 0. Users in an app will be confused to see a number of bikes at the station if they are not able to rent them. From what I know, this is how consumers interpreted it as well.

As @barbeau mentions, GBFS is intended for bikeshare users, not operators.

[albloptor]

In my opinion, num_bikes_available should be the number of bikes at the station available to rent IN CASE is_renting is true, regardless of the system working hours. Otherwise, what's the point of having is_renting and is_returning?

Moreover, a user may want to know how many bikes there are at a station at any moment in time. For example, if the system opens at 6am, the user may want to know how many bikes there are at 5:30am before starting his commute. This is not possible if num_bikes_available is 0 during non-working hours.

I believe it would be more useful for the user to have something like this:

During working hours:

- "is_renting" = 0/1
- "is_returning" = 0/1
- "num_bikes_available" = available bikes at the station (not broken) that would be "rentable" if "is_renting" was 1.

During non-working hours:

- "is_renting" = 0
- "is_returning" = 0
- "num_bikes_available" = available bikes at the station (not broken) that would be "rentable" if "is_renting" was 1.

@dsgermain, you mention that

if is_renting is false, num_bikes_available should always be 0

By overlapping the meaning of two different fields in the data feed, the specification becomes less flexible and more complicated because implementations need to ensure that this condition is met.

I believe each of the fields in the GBFS data feed should be completely independent from each other. This way, it is more flexible as it can cover more situations and edge cases.

In summary, as a user, there are several questions I need to have answers to from the feed:

1. Is this station renting bikes right now?
2. Is this station accepting bikes right now?
3. How many usable bikes (non-broken, non-locked-in) are there at the station? Regardless of the previous questions.
4. How many usable spaces are there at the station? Regardless of the previous questions.

[barbeau]

For me, if is_renting is false, num_bikes_available should always be 0

Yes, this is what I was trying to communicate. My point was that we shouldn't overload the num_bikes_available field with different meanings based on the value of another field.

[dsgermain]

@albloptor
num_bikes_available refers explicitly to available bikes in the name of the variable and the definition ("Number of bikes available for rental"). When the station is not renting, the bikes are not available.

If you want to change the spec, I have no trouble with that, but current systems are implemented with this meaning in mind and this is a breaking change.

[albloptor]

@dsgermain
My point is that if is_renting is false, then the fact that num_bikes_available (in its current meaning) = 0, is obvious/redundant.

I completely understand that there are clients implementing the spec in that way and we don't want to break them. If the spec cannot be changed because of this reason, then what if two new fields were added to the feed?

"num_usable_bikes" - Number of non-broken bikes at the station.
"num_usable_spaces" - Number of usable spaces at the station.

This way we don't break anyone and we gain the extra functionality.

[Noe-Santana]

@dsgermain, about the systems that are using the GBFS I´m not sure if this porposal to standarize the way these values perform will be a breaking change.

There are 38 systems of the 78 that are working with Bcycle and as far as I see Bcycle is reporting the number of bikes that by itself are available for rent (because are not broken or blocked) at stations that are not allowing rents (is_renting: 0), even citibike in NY is showing the number of bikes available when a station is not renting.

[barbeau]

@Noe-Santana Would you or others be willing to do a survey of all systems in https://github.com/NABSA/gbfs/blob/master/systems.csv to see how many follow the rule if is_renting is false, num_bikes_available should always be 0?

[jcn]

I would also like to know how many GBFS producers implement num_bikes_available as "0" if is_returning is false.

Regardless of what we decide, the spec needs to be clarified, since I don't think either scenario is obvious (I had always intended is_returning and num_bikes_available to behave independently of each other, but can see why people may have interpreted it the other way).

[dsgermain]

@albloptor I like the idea of adding

"num_usable_bikes" - Number of non-broken bikes at the station.
"num_usable_spaces" - Number of usable spaces at the station.

[albloptor]

Hi guys, I've created a pull request with the changes proposed in the conversation above. Maybe we can further discuss the changes there: #95

[mplsmitch]

@Noe-Santana - you opened this because you said there was a lack of clarity around how 'is_renting' and 'num_bikes_available' were defined and not all systems were using them in the same way. Adding two additional fields may enable you to do your analysis but it makes the defining the now 6 fields in question that much more of a challenge. If we're adding complexity through additional fields, we've got to refine the definitions in order to solve the lack of clarity problem. As it's currently written in #95 'num_bikes_available' and 'num_usable_bikes' are indistinguishable if you haven't read this thread.

It seems to me that this whole thing could be handled by changing the definition of 'num_bikes_available'
to Number of bikes available for rental when 'is_renting' = 1. The number of bikes at the station can persist when the system is closed overnight and the 'is_renting' flag can be used to indicate there are no bikes for rent. Would this solve the problem?

Supposing we added the two additional fields, here are a couple of questions -

It's common to have a station out of service due to technical issues, road construction or other reasons. Often there are bikes in the station when this happens. When the station will return to service may be unknown but it could be days or weeks. Currently we would set 'is_renting' = 0 and 'num_bikes_available' = 0. How would the proposed fields work in this scenario?

My system operates seasonally from April to November. During the period of November to April when we're not in service, how would the proposed fields work in relation to what's contained in system_calendar.json?

[albloptor]

It seems to me that this whole thing could be handled by changing the definition of 'num_bikes_available'
to Number of bikes available for rental when 'is_renting' = 1. The number of bikes at the station can persist when the system is closed overnight and the 'is_renting' flag can be used to indicate there are no bikes for rent. Would this solve the problem?

@mplsmitch I completely agree with you that these two new fields I propose are unnecessary if num_bikes_available and num_docks_available are re-defined to reflect the non-broken bikes and docks at the station regardless of the flags.

My opinion, for the two scenarios you propose, is that is_renting = 0, num_bikes_available = 0 and num_usable_bikes = X. The word usable may be ambiguous, so we could consider renaming it to something different. The definition is really non broken bikes at the station that could potentially be rented if "is_renting" was 1.

I am also interested to see what @Noe-Santana 's opinion is.

[Noe-Santana]

Hello everyone. sorry for my delayed response.

I would suggest not to add more fields, as Mitch rightly propose, it can be solved by taking advantage of the present fields and giving them extended functionality trough a precise definition.

"num_bikes_available" = Number of functional bikes at the station, to know if these can be used, refer to "is_renting" value.
"num_docks_available" = Number of functional docks at the station, to know if these can be used, refer to "is_returning" value.

[barbeau]

as Mitch rightly propose, it can be solved by taking advantage of the present fields and giving them extended functionality trough a precise definition.

"num_bikes_available" = Number of functional bikes at the station, to know if these can be used, refer to "is_renting" value.
"num_docks_available" = Number of functional docks at the station, to know if these can be used, refer to "is_returning" value.

True, but again, this is breaking functionality for anyone who has built a GBFS consumer that assumes num_bikes_available provides currently rentable bikes, independent of the is_renting field value. I currently have two such user-facing clients, and the OpenTripPlanner (OTP) project also makes this same assumption (I've opened a companion issue on OTP at opentripplanner/OpenTripPlanner#2563 that points to this GBFS issue). is_renting is not currently consumed by OTP.

[Noe-Santana]

@barbeau, you´re also right, it will represent a need of adjustment for the current developments that use the GBFS, but it will happen in any of the cases, the purpose is to guide these efforts to a standar that represents more versatility and can meet the needs of more approaches.

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.

11 systems are working with the PBSC technology, at the non service hours the "num_bikes_available" on all the stations changes to "0" but when a station is setted as "not in service" the "is_renting" flag changes to "0" while the field "numb_bikes_available" mantain with the amount of functional bikes at the station.

Other systems that we found that are mantaining the values of bikes and docks available are Citibike NewYork, Divvybikes Chicago and Socialbicycles Phoenix.

Right away, developments like the OpenTripPlanner (OTP) project should consult the "is_renting" and "is_returning" flags for these 28 to 52 systems, otherwise it will not recognize that a station is not able to give bikes even when the num_bikes_available is diferent to "0".

[barbeau]

@Noe-Santana Thanks for putting together some numbers! You're right, OTP will currently incorrectly show bikes available on those systems when there aren't any.

So this is a bit of a mess, then.

Are other vendors monitoring this issue that aren't reflected in the above numbers? If so, could you say how you use the is_renting flag, and if you ever show num_bikes_available > 0 when is_renting is false?

[jcn]

I'd like to make an attempt at a pragmatic proposal to moving forward.

It seems like there are two issues at play here:

1. Correcting the spec to remain as concise and expressive as possible, regardless of any current implementation issues (i.e. correcting the ambiguity and pretending we live in a world where there are no consumers or producers already using the spec)
2. Communicating with and updating producers and consumers of this data to reflect the corrected spec in the most reasonable and friendly way possible

On the matter of issue 1, it seems that since is_renting does exist in the spec, and since the existing fields need to be clarified anyway, and that clarifying the existing fields these should provide sufficient data for anyone looking to consumer raw bike/dock numbers, I propose that we move forward with the correction of the spec to reflect that is_renting should be considered an on/off flag for the rental status of the station, regardless of num_bikes_available, and that num_bikes_available should always reflect the actual number of non-broken bikes-in-docks.

Which then brings us to issue 2, how to actually move forward. My proposal here would be to give consumers some period of time (perhaps 1 month) to first implement the consumption of is_renting. During that time, producers would agree not to change their implementations, to allow for as graceful a transition as possible. After that time, then producers would update their GBFS feeds to reflect the corrected spec.

I know this is not the most graceful or ideal situation, but I'm hoping we can collectively come up with a way forward that keeps the spec as concise as possible, while solving this particular problem. What do you all think?

[albloptor]

I totally agree with @jcn. I believe that we should adjust the definition of the existing fields and communicate the change to the clients implementing it, allowing them a reasonable amount of time as a transition. We should probably refer to this issue for reference.

[barbeau]

@jcn Generally I think that's a reasonable plan, although I'm concerned about producers actually rolling out timely changes to ensure conformity. From an outsiders perspective, it doesn't seem like a large percentage of producers are actually engaged here on Github.

How would we:

1. Notify producers of this issue?
2. Ensure that systems are changed over promptly on the agreed-upon date?

[dsgermain]

If we all agree on the change and that we don't mind some consumers breaking for a while (as they won't be notified because we don't know who they all are), I have not problem implementing this in an upcoming version.

[barbeau]

I've been thinking more on this, and the proposed v1.1 in #92, in context of knowing which producers have updated their systems.

I think GBFS would benefit from explicit version_code (an integer) and version_name (a string) fields in all the .json files. version_code would start at 1 and increment on each update that changes semantics of the spec, and version_name is semantic versioning such as 1.1.

This would allow consumers to easily know which systems have been updated and which have not (assuming we keep good documentation of version history).

We did something similar with GTFS-realtime v2.0 - the semantics of required and optional fields changed, so producers can bump gtfs_realtime_version when they adopt the new semantics so consumers would know what to expect.

Any thoughts on this?

[jcn]

@barbeau I would propose that this discussion about versioning be continued in #15 (a very old issue!) and that we use this thread to finalize the mechanics of how this change will be made.

Unfortunately, I don't even think that versioning will help this particular issue since different producers already implement the fields differently, thus the version wouldn't actually indicate any consistency anyway.

[barbeau]

Unfortunately, I don't even think that versioning will help this particular issue since different producers already implement the fields differently, thus the version wouldn't actually indicate any consistency anyway.

I disagree - the presence of the version (assuming it's introduced with this change) would indicate consistency among the feeds that have the version number. It means the producer has adopted the new consistent field definition. Otherwise, without some analysis of the data coming out of each feed (i.e., does the feed zero out availability when not renting bikes? And does the 0 actually mean there aren't any bikes there, or just a different interpretation of the original field definition?) we won't know whether each producer has adopted the new consistent semantics - in other words, we'll be wondering if the discussion in this thread actually had any impact on deployed GBFS feeds.

I would propose that this discussion about versioning be continued in #15 (a very old issue!) and that we use this thread to finalize the mechanics of how this change will be made.

That's fine, although I think if we adopt this without some method to track adoption we'll be left wondering how many producers have actually implemented it.

[heidiguenin]

Hey all! Now that we're actually moving toward a versioning scheme and then likely making use of it right away with #147, I'd like to suggest we bundle up a few other small breaking changes, including this one.

Is the general consensus that @Noe-Santana's solution is the way we want to go here?

[barbeau]

@heidiguenin Yes, I'm good with the solution proposed by @Noe-Santana in this comment:
#94 (comment)

We just need to be sure that the text clearly explains the dependency of these counts on is_renting.

[jcn]

bundle up a few other small breaking changes, including this one.

In my mind, this is the kind of "bug fix" to the spec that should be codified in a minor version change.

To the point made in #94 (comment) (which I agree with), the presence of the minor version in a published feed would mean that the clarified spec is being conformed to.

And just to be clear, the clarification is that the num_bikes_available and num_docks_available always refer to the physical state of the bikes/docks, whereas is_renting refers to the logical state of whether or not the system is actually allowing rentals at the time, so both fields must be considered before indicating whether bikes can be rented from the station, right?

[barbeau]

And just to be clear, the clarification is that the num_bikes_available and num_docks_available always refer to the physical state of the bikes/docks, whereas is_renting refers to the logical state of whether or not the system is actually allowing rentals at the time, so both fields must be considered before indicating whether bikes can be rented from the station, right?

👍

[heidiguenin]

I've opened a PR for this - #195 - so let's continue any conversation there.

#188, the proposal for versioning will close later today, so I'd love get this issue settled in the coming weeks, too!