Use cases PB

home > Use cases > Use cases Planning & Booking

PB1

Description

The end-user has found a specific asset on the street (like a free parking spot, a bike, or shared car) or a route planner has returned all needed information to book an asset (like a tram line, bus, or train seat). This information is enough to book the asset directly.

Implementation

Type	object	remarks
Endpoint	POST /bookings/one-stop	result.status = CONFIRMED (in case of AUTO_COMMIT) or PENDING (otherwise)
Process identifier	booking.ONE_STOP
Process identifier	booking.AUTO_COMMIT	don't use this one in case you want to provide a 2-phase booking, see PB3

Applies to Mostly public transport & free-floating/zone-floating shared mobility providers (e.g. bikes, scooters, cars). But also parking operators. Actually, everything I can book 'here-and-now'.

PB2

Description

As a TO, you want to be able to serve multiple options for a trip request. Like (PT case) serving a first-class or second-class ticket (or even day, week, or month tickets), (shared-car case) different types of cars, with or without insurance, etc.

Implementation

Type	object	remarks
Endpoint	POST /planning/offers	provides the bookable options
Endpoint	POST /bookings	book one of the options, result.status = CONFIRMED (in case of AUTO_COMMIT) or PENDING (otherwise)
Process identifier	booking.NORMAL
Process identifier	booking.AUTO_COMMIT	don't use this one in case you want to provide a 2-phase booking, see PB3

Applies to All

PB3

Description

An MP or reseller often combines multiple legs together to establish one trip. Each part (legs) must be found and booked separately. In case one of the suppliers of the legs offers something, but during the booking process the offer is retracted, it cannot be confirmed. In that case, it might also be needed to roll back the other bookings. Therefore the default TOMP process provides a 2-phase booking. When you're not complying with it (and use 'AUTO_COMMIT'), the MP needs to CANCEL the booking, with possible financial consequences.

Implementation

Type	object	remarks
Endpoint	POST /bookings/{id}/events	operation: COMMIT

Applies to All TOs that want to integrate into MaaS, whilst keeping fines when cancelling a leg.

PB4

Description

As a TO I would like to allow canceling a booking in order to release a claimed asset (and optionally refund something).

Implementation

Type	object	remarks
Endpoint	POST /bookings/{id}/events	operation: CANCEL

Applies to All TOs that will refund cancelled trips before the trip is started

PB5

Description

As a TO I would like to provide a digital ticket, together with the committed booking in order to provide proof (for inspection or entrance/exit) of travel rights.

Implementation

Type	object	remarks
Endpoint	POST /bookings/{id}/events	operation: COMMIT, provide the digital ticket in legs[0].ticket

Applies to PTO

PB6

Description

As an MP I would like to be able to communicate that the traveler is less abled in order to request a smooth ride, with assistance if needed.

Implementation

Type	object	remarks
Endpoint	POST /planning/offers	In the request, the traveler's aspects can be specified, in the requirements.abilities (referring to the CROW traveler's dictionary).

Applies to PTO, taxi, shared-cars, flight, ...

PB7

Description

As an MP I would like to indicate that the traveler brings along personal item(s), like a bike in order to facilitate that the items are transported as well.

Implementation

Type	object	remarks
Endpoint	POST /planning/offers	In the request, the traveler's aspects can be specified, in the requirements.bringalong (referring to the CROW traveler's dictionary).

Applies to PTO, taxi, flight

PB8

Description

As an MP I would like get a price indication for a personalized leg in order to inform the customer how much it will take to get there.

Implementation

Type	object	remarks
Endpoint	POST /planning/inquiry	This endpoint can be called without any consequences to the caller. It must mainly be fast, which might be more important than 100% accurate.

Applies to Every operator using dynamic pricing.

PB9

Description

As a TO I would like to respond to a booking request, although I'm not completely convinced I can guarantee it (the so-called postponed commit scenario) in order to get some time to arrange everything needed to deliver the service.

Implementation

Type	object	remarks
Endpoint	POST /planning/offer	returns options
Endpoint	POST /bookings/	result: the status of the booked option is 'CONDITIONAL_CONFIRMED'
Process identifier	booking.POSTPONED_COMMIT	to indicate this process flow

Applies to Taxi

PB10

Description

As a TO I would like to confirm that the booking is confirmed in order to make the customer happy (related to PB9)

Implementation

Type	object	remarks
Endpoint	POST /bookings/{id}/events	operation: COMMIT, SENT BY THE TO TO THE MP!, the status of the booking will be 'CONFIRMED'
Process identifier	booking.POSTPONED_COMMIT	to indicate this process flow

Applies to MP that wants to use taxis

PB11

Description

As a TO I would like to tell that the booking is NOT confirmed in order to give the MP/reseller time to arrange something else (related to PB9)

Implementation

Type	object	remarks
Endpoint	POST /bookings/{id}/events	operation: DENY, SENT BY THE TO TO THE MP!, the status of the booking will be 'RELEASED'
Process identifier	booking.POSTPONED_COMMIT	to indicate this process flow

Applies to MP that wants to use taxis

PB12

Description

As a TO I would like to inform that you can book my assets in the future in order to use my services in the right way.

Implementation

Type	object	remarks
Process identifier	planning.PLANNING_BASED	'departureTime' can be 'now', it doesn't require to be in the far future.

Applies to Shared cars, trains, buses, bikes, ..

PB13

Description

As a TO I would like to inform you that you can find my assets on a map for direct usage (free-floating) in order to use my services in the right way.

Implementation

Type	object	remarks
Process identifier	planning.ASSET_BASED

Applies to Bike, scooter operators, street parking

PB14

Description

As a TO I would like to inform you that you can find my assets in specific locations (stations, hubs) in order to use my services in the right way.

Implementation

Type	object	remarks
Process identifier	planning.LOCATION_BASED

Applies to Station based operators, trains, buses, (taxis), off-street parking, ..

PB15

Description

As a TO I would like instruct that you have to supply an estimated distance you want to travel in order to serve assets with enough fuel, battery power.

Implementation

Type	object	remarks
Process identifier	planning.USE_ESTIMATED_DISTANCE

Applies to Shared cars, e-bikes

PB16

Description

As a TO I would like to inform you how you can discover the asset's identifying name/id in order to use it directly in the booking process.

Implementation

Type	object	remarks
Process identifier	planning.BLUETOOTH_SCAN	using a Bluetooth scan, you can find nearby assets and their IDs. Supply these in the field 'use_assets'.
Process identifier	planning.QR_SCAN	The ID of the asset can be found in a QR code on the asset. Supply the QR code content in the field 'use_assets'.
Process identifier	planning.NFC_SCAN	The ID of the asset can be found using NFC. Supply the NFC content in the field 'use_assets'.
Process identifier	planning.BARCODE_SCAN	The ID of the asset can be found in the barcode on the asset. Supply the barcode content in the field 'use_assets'.
Process identifier	planning.MANUAL_ENTRY	The ID of the asset can be found somewhere on the asset, to be entered manually in the app. Supply the entered code in the field 'use_assets'.
Process identifier	planning.EXACT_ID	The ID of the asset can be found in the data that is supplied for the map (/available-assets). Supply the ID in the field 'use_assets'.

Applies to Scooters, bikes, buses, parking

PB17

Description

As a TO I would like to get information about the previous leg in order to pick you up at the right location OR give discounts. In case you want to use it for discounts, you still have an agreement between the two organizations about the format.

Implementation

Type	object	remarks
Endpoint	POST /planning/one-stop	in the request there is previousLegInfo.
Endpoint	POST /planning/offers	in the request there is previousLegInfo.

Applies to Taxi, bus, parking

PB18

Description

As a TO I would like to request neglectable time between the offer I serve and the booking request (no user interaction in between) in order to integrate with my existing back end.

Implementation

Type	object	remarks
Process identifier	planning.ATOMIC_PLANNING_AND_BOOKING

Applies to Mostly bikes

PB19

Description

As a TO | request the age or other personal aspects | give legal ground to the booking

Implementation

Type	object	remarks
Endpoint	POST /planning/offers	in the resultset the booking.legs.conditions a requiredBookingData object must be specified OR
Process identifier	planning.MANDATORY_TRAVELER_AGE	when this is specified, this applies to all offers
Endpoint	POST /bookings/	in the request 'customer.age' (or other required field) must be supplied

Applies to e.g Age restricted mobility: Car, E-bike, scooter.

PB20

Description

As a TO | request specific location information (like station or stop references, exact street address, ..) | avoid problems at the pick up or drop off locations

Implementation

Type	object	remarks
Endpoint	POST /bookings/	In the booking request specific location information with the bookingRequest.from and bookingRequest.to that contain place objects. (stopReference, stationId or a physicalAddress).
Process identifier	planning.MANDATORY_FROM_STATION_ID	require mandatory from station id.
Process identifier	planning .MANDATORY_TO_STATION_ID	require mandatory to station id.
Process identifier	planning.MANDATORY_FROM_STOP_REFERENCE	require mandatory from stop reference (e.g stopReference: NL:S:13121110 or stopReference: BE:S:79640040).
Process identifier	planning.MANDATORY_TO_STOP_REFERENCE	require mandatory to stop reference (e.g stopReference: NL:S:13121110 or stopReference: BE:S:79640040).
Process identifier	planning.MANDATORY_FROM_ADDRESS	require mandatory from address (e.g a taxi service might want to implement this).
Process identifier	planning.MANDATORY_TO_ADDRESS	require mandatory to address (e.g a taxi service might want to implement this).

Applies to Station based operators, trains, buses. Taxi.

PB21

Description

As a TO | request an arrival time, the departure time is less relevant | get the traveler on time on the destination

Implementation

Type	object	remarks
Endpoint	POST /planning/offers	In the planning request give a arrivalTime. If only the arrival time is specified, this is an implicit request for a guaranteed arrival at that time.
Process identifier	planning.MANDATORY_ARRIVAL_TIME	when this is specified this applies to alle offers.

Applies to All mobility not operated by the customer.

PB22

Description

As a TO | request a first departure time | be able to create schedules

Implementation

Type	object	remarks
Endpoint	POST /planning/offers	In the planning request give a departureTime
Process identifier	planning.MANDATORY_DEPARTURE_TIME	when this is specified this applies to alle offers.

Applies to All mobility not operated by the customer.

PB23

Description

As a TO | request a time window where the complete trip has to be completed in | be able to create schedules

Implementation

Type	object	remarks
Endpoint	POST /planning/offers	In planning request give a departureTime and arrivalTime.
Process identifier	planning.MANDATORY_DEPARTURE_TIME	together with planning.MANDATORY_ARRIVAL_TIME require a time window on all offers.
Process identifier	planning.MANDATORY_ARRIVAL_TIME	together with planning.MANDATORY_DEPARTURE_TIME require a time window on all offers.