[FEATURE REQUEST] Future asset booking spot capacity

eborremans commented 2 years ago

Future asset booking spot capacity

Use Case:

As an MP I want to know the total TO booking capacity at a certain location for a certain period of time.

For instance, location X has the capacity for booking 8 bikes during the summer vacation period 01-06 - 31-08.

Let's say that on June 2nd to 4th, 4 bikes have been booking for location X:

Asset   | start date       | end date         |
bike 1: | 02-06-2022 08:00 | 03-06-2022 17:00 |
bike 2: | 02-06-2022 08:00 | 04-06-2022 13:00 |
bike 3: | 02-06-2022 12:00 | 03-06-2022 24:00 |
bike 4: | 03-06-2022 08:00 | 04-06-2022 24:00 |

This will lead to the following booking spot availability for indicated example periods:

| period start     | period end       | available spots |
| 02-06-2022 04:00 | 03-06-2022 11:00 | 6               |
| 02-06-2022 08:00 | 03-06-2022 15:00 | 5               |
| 02-06-2022 00:00 | 03-06-2022 21:00 | 5               |
| 02-06-2022 17:00 | 03-06-2022 21:00 | 4               |
| 04-06-2022 02:00 | 04-06-2022 10:00 | 5               |

This basically means that for instance, the maximum nr of bikes someone can book for the period 02-06-2022 04:00 to 03-06-2022 11:00, is 6, even though at the start of that period there are still 8 "booking spots available. The algorithm should always look at the minimum available spots during the given period.

So we would like to have an endpoint that gives us the available number of booking spots for the indicated period for a certain asset type.

Urgency

Major (the TOMP API works as advertised but this is really necessary to implement), because these booking scenarios are common for service desks who want to inform customers about future availability of assets, or rather booking spots for assets.

Additional context

A common scenario involves holiday parks where customers can rent bikes for the whole family. There are typically always fewer bikes than cottages so service desk needs to be informed up front how many booking spots are still available. In many cases this information can also be used to increase the asset supply.

Describe the solution you'd like

POST /operator/bookings/available-spots request:

{
  "from" : ...
  "assetTypeId" : ...
  "departureTime" : ...
  "arrivalTime" : ...
}

response:

{
  "from" : ...
  "assetTypeId" : ...
  "departureTime" : ...
  "arrivalTime" : ...
  "nrOfAvailableBookingSpots" : ...  
}

Describe alternatives you've considered

Alternatively you could add a variation of /operator/available-assets that use POST and a request: POST /operator/available-booking-spots with the following request:

{
  "allAssets" -- to request all booking dates for all assets of indicated type for the indicated locations and period
  "departureTime" -- to indicate the start of the period
  "arrivalTime" -- to indicate the end of the period
}

The response structure would be the same as for GET /operator/available-assets but for an added field: "totalBookingCapacity" which indicates the total number of booking spots available, so the client can do its own math regarding availability.

This response information could for instance be used to draw calendars that show asset availability during a time period. Note that this solution may not be desirable for large TOs with many assets per location.

matt-wirtz commented 1 year ago

Hi!

I think in general I have pretty much the same use case. In my case we are talking about bike parking facilities e.g. bike boxes which can be booked in advance for a specific time period. So the availability of the asset in the future needs to be queried.

Describe the solution

In my understanding the use case could be handled by using the POST /planning/inquiries endpoint. Specify the "from" by providing a specific station or like below the coordinates of the place where the vehicle/asset is needed. Provide the time period for the booking by setting departureTime to the start time point and arrivalTime to the end time point:

{
    "from": {
        "coordinates": {
            "lng": 8.169639,
            "lat": 52.253279
        }
    },
    "radius": 500,
    "departureTime": "2022-11-10T00:00:00.000Z",
    "arrivalTime": "2022-11-11T00:00:00.000Z",
    "useAssetTypes": [
        "BikeParkingFacilityTypeOne",
        "BikeParkingFacilityTypeTwo"
    ]
}

In the example above only one asset is queried for. If multiple assets/vehicles are requested one would need to add this info. There is already a "nrOfTravelers" parameter but I think if it comes to vehicles and assets one should rather add e.g. a nrOfEntities parameter in the spec.

In the response the nrAvailable field indicates if the requested quantity of assets/vehicles is available.

General thoughts

The /operator/... endpoints of TOMP have strong ties to the GBFS specification. Maybe they can be aligned even closer in the future.

With this in mind I don't think it would make sense to extend the functionality of the /operator/... endpoints without having GBFS going in the same direction.

In addition the proposed solution to use POST /planning/inquiries allows to immediately jump into the booking module in order to book the vehicles/assets. When utilizing a new /operator/bookings/available-spots endpoint a booking could not be triggered right away.

edwinvandenbelt commented 1 year ago

I think the availability endpoint should be refactored. Taking GeoJSON as the base format, each feature is a station (with availability per asset type, including free docks per asset type or in general), a free-floating area (with availability per asset type) or an asset (with availability). The availability should be formatted as an array of time spans [[from, until], [from, until], etc]. But this ends up in becoming a breaking issue and therefore reserved for V2.0

TOMP-WG / TOMP-API