Future availability of vehicle types by station

[richfab]

What problem does your proposal solve? Please begin with the relevant issue number. If there is no existing issue, please also describe alternative solutions you have considered.

Following the discussion in #616

Operators want to be able to describe the future availability of their services, for example to display it in trip planners. This is particularly useful for systems that allow vehicles to be booked in advance (e.g. carsharing).

What is the proposal?

Add a new endpoint vehicle_type_availability.json which describes the future availability of each vehicle type by station.

Is this a breaking change?

• Yes
• No
• Unsure

Which files are affected by this change?

Proposal to add a new endpoint: vehicle_type_availability.json

[mplsmitch]

@richfab How do you handle time_slots when they're is no future booking to set the until?
Should it be null?
"from": "2024-12-24T08:15Z", "until": "Null"

[richfab]

Thanks @mplsmitch. I was just going to ask if we should make until OPTIONAL for when a vehicle type is available all the time starting from a date.
{"from": "2024-12-24T08:15Z"}

[mplsmitch]

I like that

[Lefois]

Thank you @richfab for open this PR! Indeed a very nice addon for many use-cases that I would vote for.

As far as I understood the proposed file is optional. Also I understood from the discussion in issue 616 that availabilities based on certain vehicles are not wished by many operators due of privacy reasons, which is understandable. However, the carsharing provider in our region (and one of the biggest in Germany), stadtmobil has availabilities only vehicle-wise. There are no "vehicle types". It would completely make sense for me to add availabilities as well to vehicles. So that we say it is optional to add whethervehicle_type_availability.json or as similar vehicles_availability.json

If I think about our forecast idea for micromobility (issue 612) we might also remove the "Not supported for free floating (dockless) vehicles" constraint for the vehicles.

Once accepted, we would start implementing a reference implementation for vehicles right away as well as we would support the vehicle_types approach and get an implementation ready.

[futuretap]

I second this, @Lefois. I helped the folks at CommonsBooking, a WordPress plugin to manage small, mostly volunteer-based (cargo) bike operations with their GBFS API. Their GBFS adaption suffered from the lack of availability modeling in GBFS. The idea of CommonsBooking is to manage reservations for all sorts of items, including vehicles. They allow hour- or day-based reservations. So for their data model a vehicle-based availability is most appropriate.

[matt-wirtz]

@Lefois Thanks for bringing up this topic again. And that brings us back to the very beginning of the discussion where we already suggested to provide future availability by vehicle.
Having the future availability by vehicle/asset would make things much easier here. For the producer the availability data by vehicle is readily available. I think there is no MSP who already has it by vehicle type. So that needs to be processed. The consumer side systems probably are more designed to work with per vehicle information. So less effort there too. But they have the advantage that as a workaround they could easily propagate the per vehicle type information to virtual vehicles - maybe causing some issues down the road.
So strong support for having the option to provide future availability information by vehicle or by vehicle_type.

[richfab]

I observe that the need for a vehicle-based model is supported by several data producers and data consumers.

For this reason, I will close the current PR and create a new PR #726 'Future availability by vehicle' to continue the discussion.

In this discussion, let's keep in mind the guiding principle of GBFS which is that data is public and useful to travelers.

Thanks! 🙏

[eborremans]

@richfab I think this PR is still very relevant. My biggest request would be to facilitate actual availability or ate least more than 'at least one', for operators who don't care about this aspect of privacy. My company only supports booking by vehicle type, but we do communicate that actual number of available vehicles. Or at least a number that is larger than 1. This enables us to present bookings in a web shop like fashion where the customer can immediately see how many assets are available for a certain time period. This does not need to be the actual number of bookings available, but should typically be large enough to serve the typical customer for a specific business case. As I showed in an example here: #616 (comment) consider this typical use case: A vacation park where a family wants to book 4 bikes for the period when they are staying at the park. They want to know up front if 4 bikes are available during their vacation period. In our specific use cases they are not (allowed to be) interested in specific vehicles, they just want a specific type.

Let's assume that the operator has 20 reservation spots, but any single customer on average books 2 to 3 vehicles with exceptions of 8 vehicles, than in that case the operator can show - say - 10 available vehicles of that type. It will serve the customer and not expose the actual capacity of the operator. Malicious forces can only acquire this information by actually making multiple bookings (and cancelling them afterwards).

So my request would be to add an optional field totalNrAvailable. Maybe even maxNrOfAssets (So customers can be shown X available out of Y). However, I realize this brings us back to my original concern (see also https://github.com/MobilityData/gbfs/pull/726#issuecomment-2684670551). Since existing bookings all have different start and end times the exact availabilities for a certain asset type are scattered all over the place. So the response would need a different structure to accomodate this. Something like this maybe (copied from (https://github.com/MobilityData/gbfs/pull/726#issuecomment-2684670551))

Request:

• Asset type
• Period start
• Period end

Time slot size (optional?)
Response:
For a certain (typically large) period, per asset type, an array of time slots with the availability for that type for each time slot:

• Asset type
• Period start
• Period end
• Time slot size (optional?)
• Availabilities: [{
  • start
  • end (optional?)
  • totalNrAvailable
  • maxNrOfAssets (optional?)
  • pricing info
    }]

Questions:

• timeslot size?
• variable per request, station, organisation, globally, etc?
• are all timeslots equally sized?
• pricing info per timeslot or per asset type or other?

Depending on different factors, the information will almost certainly be inaccurate. If the granularity of booking periods for individual bookings is more fine grained than the timeslot size, this will lead to small inaccuracies. However, I doubt the inaccuracy will be relevant for most common use cases if we manage to choose the right timeslot sizes. I know from experience that calculating the above can be quite tricky, especially if bookings are vehicle type based instead of vehicle id based. However, this offers great flexibility to our customers.

In any case, our customers would definitely need a type based endpoint.