Future availability by vehicle

[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 and #722

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, cargo bike share, etc).

What is the proposal?

Add a new OPTIONAL endpoint vehicle_availability.json which describes the future availability of each vehicle.

Is this a breaking change?

• Yes
• No
• Unsure

Which files are affected by this change?

Proposal to add a new OPTIONAL endpoint: vehicle_availability.json

Example

{
  "last_updated": "2023-07-17T13:34:13+02:00",
  "ttl": 0,
  "version": "3.1-RC2",
  "data": {
    "vehicles": [
      {
        "vehicle_id": "45bd3fb7-a2d5-4def-9de1-c645844ba962",
        "vehicle_type_id": "abc123",
        "station_id": "station1",
        "pricing_plan_id": "plan3",
        "vehicle_equipment": [
          "child_seat_a"
        ],
        "availabilities": [
          {
            "from": "2024-12-24T08:15Z",
            "until": "2024-12-24T09:15Z"
          },
          {
            "from": "2024-12-25T10:30Z"
          }
        ]
      },
      {
        "vehicle_id": "987fd100-b822-4347-86a4-b3eef8ca8b53",
        "vehicle_type_id": "def456",
        "station_id": "86",
        "availabilities": [
          {
            "from": "2024-12-24T08:45Z"
          }
        ]
      }
    ]
  }
}

[matt-wirtz]

Thanks @richfab.
I think the vehicle_equipment and pricing_plan_id would be necessary too as I explained in the original proposal: #616 (comment)
I'm not sure about the home_station_id being optional. If the vehicle is currently not available it will not show up in vehicle_status either. So it's not known where this vehicle is located and could be found rendering the info when it's available useless. So I think that should be REQUIRED too.

[richfab]

Hi @matt-wirtz,

As suggested, I added pricing_plan_id and vehicle_equipment to the proposal.

I renamed home_station_id to station_id to broaden the potential use cases.

I made the field station_id Conditionally REQUIRED. Indeed, we could imagine a shared mobility system with no station at all (i.e. all vehicles are within a small perimeter), in this case station_id would not be required.

Do you or anyone else see any other things that should be changed in the proposal? If not, I propose to open a vote in 7 days.

Thank you very much for your contributions and patience 🙏

[futuretap]

I made the field station_id Conditionally REQUIRED. Indeed, we could imagine a shared mobility system with no station at all (i.e. all vehicles are within a small perimeter), in this case station_id would not be required.

Couldn’t we handle that case with is_virtual_station = true, including a station_area? Otherwise we could end up in a situation where a vehicle-based reservation is made based on the current availability but then the vehicle is moved to the other side of the city. We would need some language to forbid that case. Imo it’s easier to make station_id always required. Then this case simply can’t happen.

[richfab]

Good points @futuretap. I made station_id REQUIRED.

Does anyone see anything else that should be changed in the proposal? If not, a vote will be opened in 7 days. Thanks!

[richfab]

Thank you to everyone who contributed to this proposal in #616, #722 and #726 🙏

I hereby call a vote on this proposal. Voting will be open for 10 full calendar days until 11:59PM UTC on Friday, February 28.

Please vote for or against the proposal, and include the organization for which you are voting in your comment.
Please note if you can commit to implementing the proposal.

Governance on the spec change process can be found here.

[matt-wirtz]

+1 from Hacon (consumer) are going to implement this

[Lefois]

raumobil votes for the proposal. We are going to implement this as a consumer.

[futuretap]

+1 from Where To? / FutureTap (consumer). We plan to implement this.

[richfab]

Please feel free to mention this vote to operators who wish to produce future vehicle availability data.
At least one favorable vote from a data producer is required for the vote to pass (see governance).
Thanks 🙏

[richfab]

Voting on this PR closes in 2 calendar days.

I encourage those who are in contact with data producers who would like to publish vehicle_availability.json to ask them to vote, which is necessary for the vote to pass. @edwinvandenbelt @futuretap @Lefois @matt-wirtz @rotger711

Please vote for or against the proposal, and include the organization for which you are voting in your comment. Please note if you can commit to implementing the proposal.

Thanks!

[edwinvandenbelt]

@richfab thank you for reaching out!
+1 for TOMP-API (we can hand over this functionality).

[eborremans]

Having reviewed the spec, I am not against it perse (apart from the privacy requirement, see below), but business who work with vehicles types instead of specific vehicles cannot use this approach in any way. It make me think whether we should split booking information from vehicle availability. The latter seems to be served pretty well by this proposal, but the former is not for vehicle-type-only based businesses. Effectively, our operators won't be able to provide a feed based on this spec. In short because they do not maintain booking information for specific vehicles, only for vehicle types. [EDIT: I see now this is addressed by a separate PR #722] This is basically why I created TOMP feature request Future asset booking spot capacity.

I guess we'd need to follow up on the 'calendar' feature anyway (see also my comment here: #616 (comment) I haven't wrapped my head around what it would return in detail but something like this:

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?)
  • nrAvailable
  • 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.

One last remark that I have about the spec is regarding the privacy issue. Is a similar requirement already addressed in other files? Imho I find this requirement a bit of overkill. Afaik we do not require car operators to switch their cars' license plates after each rental. Nor do we require bike operators to replace physical QR codes on their bikes. If a malicious force wants to misuse vehicle identity they will find a way anyhow. I am afraid this unnecessarily complicates the spec and corresponding implementations. But then again, I do not know if similar requirements already exist in current specs and whether this is already legally enforced. But if you ask me I would remove it.

[eborremans]

Ah, I see this is already addressed in #722. Apologies. I will place further comments in the corresponding thread.

[mplsmitch]

@eborremans Regarding the privacy issue, please see here:

#146

[Lefois]

@richfab I am talking to operators, I already hoped to see one of them here.

[richfab]

Regarding systems that work with vehicle types instead of specific vehicles, mentioned by @eborremans:

Should we consider making vehicle_id OPTIONAL in this proposal, to allow availability to be represented either by vehicle_type_id or vehicle_id?

EDIT: If availability is needed by vehicle type, this should probably be in a different endpoint to avoid mixing concepts (for example as suggested in #722).

[eborremans]

@richfab regarding making vehicle_id optional, would that make this PR cover #722? If i understand correctly, in that case the availability period would refer to a situation where at least one vehicle of that type is available, right? However, our customers would still like to be able to return the number of available vehicles (total_nr_available) of that type for a period (not necessarily the actual amount available). If you would make that optional too, I think that would satisfy our customers requirements. As I stated before, we'd end up with many more availability records, but this is up to the operator. They will still be able to provide their data as specified in the current proposal (i.e. with vehicle_id and without total_nr_available).

[richfab]

Good point. I remove my comment. If availability is needed by vehicle type, this should probably be in a different endpoint to avoid mixing concepts (for example as suggested in #722).

[matt-wirtz]

Regarding the both concepts "vehicle availability" and "vehicle type availability".
I would not have both concepts mixed up in the vehicles array too. At least there should be two arrays: one for vehicles availability and one for the vehicle type availability.
But still I don't see a good argument for not having different endpoints. Probably depending on the business logic of the mobility provider as @eborremans explained, only one of both endpoints will be implemented in the end.

[SchiToVMZ]

Dear all, I would like to vote for the proposal: We as VMZ would like to use the new values as an information supplier for the sharing vehicles in our mobility data platforms (meta platforms) and pass them on accordingly in potential projects

[eborremans]

@matt-wirtz @richfab I agree, 2 endpoints would be fine and avoid confusion.

[eborremans]

+1 I vote for the proposal hoping that we also get a similar endpoint for vehicle type availability.
Company: Nazza/Billinghouse, we are a GBFS Data producer

[richfab]

@eborremans Would you like to provide the name of the organization you are voting for?
And can you please confirm whether you are a GBFS data producer or consumer?
This will allow me to include your organization in the voting result. Thank you 🙏

[richfab]

This vote has now closed, and it passes!

Votes in favor:

• Hacon (consumer)
• raumobil (consumer)
• Where To? / FutureTap (consumer)
• TOMP-API (consumer)
• VMZ (producer)
• Nazza/Billinghouse (producer)

There were no votes against.

This change will be part of the next MINOR Release Candidate, planned in May 2025, as per the version release cycle in the governance. Producers and consumers can still start implementing it and become First Adopters.

Thank you all for your involvement in the GBFS spec 🙏