Rides

A ride is an object that is created whenever a passenger requests a ride. The existence of a ride does not mean that a ride in the real world has taken place. Even if the ride is not accepted or canceled, an entry on the request can always be found in the table of all rides.

For viewing, filtering, and managing rides in the UI, see Rides in ioki Operator or Rides in Control Center.

Ride states

One of the most interesting entities of a ride is its state. A ride is always in exactly one of the following states.

flowchart LR
    classDef iokiGrey stroke-width:2px

    direction LR
    A[searching]:::iokiGrey --> B[ready]:::iokiGrey --> C[passenger accepted]:::iokiGrey --> D[driver accepted]:::iokiGrey --> E[picked up]:::iokiGrey --> F[dropped off]:::iokiGrey

    direction TB
    A -.-> G[canceled]:::iokiGrey
    B -.-> G
    C -.-> G
    D -.-> G
    E -.-> G

  • searching. When a ride is requested, the first state with which it’s initiated is searching. This is the case during the time the matching algorithm is looking for suitable vehicle plannings to serve this request. If it finds a possibility which matches all the requirements, the state is updated to ready. If no suitable Vehicle Planning can be found, the state is updated to cancelled.

  • ready. If the matching was successful, the state of the ride is ready. Additionally to the requested points from the passenger, ioki Platform returns Calculated Points, introduced by the Matching, Negotiation Times, and further, the corresponding fare. Now, the passenger has time to accept, that is, to book the ride. The time for which the system reserves this ride, that is, the time that the passenger has to accept the ride, is part of the product settings, see passenger-related settings. If the passenger accepts the offer in time, the new ride state is passenger accepted. Otherwise, it’s cancelled.

  • passenger accepted. When the ride was offered to the passenger, and the passenger has accepted the ride in the given time span, the state switches to passenger accepted. Now, the system waits for the acceptance of the driver associated to the selected vehicle planning. If the driver accepts in a given time span, or the system accepts the ride automatically for the driver (see automatic driver acceptance), the following state of the ride is driver accepted. If the ride is not accepted in time, the state changes to cancelled.

  • driver accepted. If the driver has accepted the ride in time or the system has automatically accepted the ride for the driver, the state is set to driver accepted. Now, the Pickup and Dropoff tasks are part of the associated vehicle planning. Once the passenger has been picked up at the calculated pickup point, the driver has to confirm this. If this has happened, the new state of the ride is picked up. But the driver has also the possibility to cancel the ride at this point, see Cancellation Reasons. If this happens, the state is updated to cancelled.

  • picked up. When the driver has confirmed, that the passenger has been picked up, the state of the ride is picked up. This should be the case until the passenger is dropped off. If the driver confirms the dropoff, the state is updated to dropped off. However, also at this point, the driver still has the possibility to cancel the ride, which updates the state to cancelled.

  • dropped off. If everything worked fine, the driver dropped of the passenger at the calculated destination point and confirmed this via ioki Vehicle App, the state of the ride is finally set to dropped off. Optionally, the passenger can now rate the ride.

  • canceled. During the whole process, until the ride state reaches dropped off, it’s always possible that a ride is canceled. This can have different reasons. Details can be found in Cancellation.

A ride is active if it is not in the state ‘canceled’ or ‘dropped off’. This is for example important for user deletion.

Automatic driver acceptance

When a passenger accepts a ride, it moves to passenger accepted and normally waits for a driver to accept it in ioki Vehicle App within the acceptance window. In several situations, the system instead accepts the ride automatically for the driver at the moment the booking is created, so the ride moves straight to driver accepted without any driver action. The driver is still notified of the new tasks.

The system accepts the ride automatically when any of the following is true:

  • No connected driver. No driver is connected to the matched vehicle through its vehicle occupation at the time of booking, for example because the app is closed, the shift has not started, or the connection dropped. Because there is no one to receive the request in the app, the system accepts on the driver’s behalf rather than waiting out the acceptance window.
  • Prebooked well in advance. The product is prebookable and the requested time is further in the future than the product’s prebooking auto-negotiation threshold. Rides booked this far ahead are accepted automatically instead of being offered to the driver right away.
  • Matched into a task list that is not currently active. The ride was matched into a vehicle planning whose task list is not the driver’s currently active task list.
  • Matched into a paused task list. The task list of the matched pickup task is paused.

If none of these apply, that is, a near-term ride matched into the active, non-paused task list of a connected driver, the ride waits for the driver to accept it in the app, subject to the acceptance window described in driver-related settings.

This automatic acceptance is engine behavior and always applies; it is separate from the Driver client automatically accepts ride requests product setting. That setting only affects a ride when a connected driver would otherwise accept it in the app, and it changes the recorded cancellation reason if the acceptance window still passes. For details, see driver-related settings.

Requested points

When searching for a ride, a passenger always specifies requested origin and destination point of his trip, including the specification of the time. In ioki Platform, there are two options how the Matching algorithm can search for rides. The default is the departure based matching. That means, when looking for a ride, the passenger can specify when he or she wants to start. The other option is an arrival based matching, which can be activated in the Settings for prebooking and ad hoc booking. In this case, the passenger can choose if he or she wants to specify the time of the destination of the trip instead.

This always fixes one end of the ride, and leaves the other one to be calculated dynamically.

This pair of origin and destination point and time are called the requested points. The requested points are fixed and do not change anymore.

Negotiation time window

When the matching algorithm finds a vehicle planning which can serve the ride request in the time span specified within the matching configuration, negotiation times around pickup and dropoff tasks are introduced. These help to keep the vehicle planning flexible to react to additionally upcoming rides and pooling.

Negotiation Times are set only once - directly at the beginning. Calculated times get updates over time, they may get pulled together (when someone in between cancels) or pushed apart (due to traffic jams), so negotiation times are the place where we store the initially negotiated times for later reference, hence the name.

If nothing unexpected, like a car breakdown or traffic jam happens, the pickup and dropoff tasks will always stay in their negotiated time windows.

For the departure, the negotiation time window is per default 5 minutes from the first offered/calculated pickup point. This is not visible for the passenger.

The negotiated time window for the dropoff is from the calculated arrival time to the time which is the maximal allowed time defined via the Allowed Travel Time in Relation to Direct Travel Time which is specified as a quality of service parameter in the matching configuration.

This stays the same for arrival based booking. In the Matching, the travel time is set to be the maximal allowed time to ensure that the dropoff task is the latest at the calculated and offered dropoff task. This induces the time window before the first calculated/offered Dropoff, that is also between the direct travel time and the allowed travel time.

Calculated points

When a ride is created, it has a requested origin point and a requested destination point. In dependence on the Matching Mode, these points are calculated to pickup and dropoff tasks and result in the so called Calculated Points. If the Matching is Station based, the calculated points are always matched to Stations. The walkways of the passenger are nevertheless taken into account, but they are not relevant for the Tasks in the vehicle planning to which the calculated times belong.

The calculated points can change during the ride due to delays and pooling. However, pooling alone never moves the calculated points out of their negotiated time windows.

A recalculation is always triggered, if an incoming vehicle position is “off route” (in time or in space). In this case, the passenger is informed about the current calculated pickup and dropoff times.

When recalculation stops

Recalculation of a calculated point stops once its task is no longer open. A task is open until it is either completed or cancelled. Both a driver in ioki Vehicle App and an operator in Control Center can complete a task, so the calculated pickup time freezes once the pickup is confirmed, and the calculated dropoff time freezes once the dropoff is confirmed. A completed task’s time no longer changes, even if the ride’s other, still-open tasks keep being recalculated.

Recalculation is not capped by the planned end of the shift. As long as a vehicle planning still has at least one open task, its calculated times keep being recalculated, and a recalculated time can land after the planned shift end.

Communicated times

The communicated times refer to the times that are communicated to the end user and are part of a calculated point. Initially, when a ride is offered, the communicated times are set to the negotiated times. Whenever a passenger is informed of a change to the pickup time via push notification, the communicated times are updated accordingly.

Additionally, the field max_communicated_times stores the maximum value of these pickup times. This value is serialized in the Driver API, enabling ioki Vehicle App to display this time so that the driver can wait for the passenger for the appropriate duration.