Matching configurations

A matching configuration belongs to a product and holds the fundamental settings and parameters that the matching algorithm uses. It also helps define the product’s service area: each matching configuration references a DRT sub area, and the union of those sub areas forms the product’s DRT area.

A product must have at least one matching configuration and can have several. Different configurations can describe different operating scenarios—for example daytime, night-time, or weekend service—and each vehicle planning uses the configuration assigned to it.

For how to create, edit, duplicate, and archive matching configurations in the UI, see Matching configurations in Control Center.

Matching mode

The matching mode defines whether the pickup and drop-off of a ride are matched by station, by address, or by a hybrid model. It is set independently for the pickup and the drop-off (default Station for both).

Station: Matching considers only stations near the requested address.
Address: Matching considers only the requested address.
Hybrid: Matching considers both nearby stations and the requested address.

If the pickup mode is Station and the drop-off mode is Hybrid, the matching algorithm can match either from Station to Station or from Station to Address. The corresponding ride options are then offered.

Additional options exclude specific matching combinations. These filter the combinations generated by the matching mode. For example, if both pickup and drop-off are Hybrid, ioki Platform can generate address-to-address, address-to-station, station-to-address, and station-to-station combinations; the prevention options remove the selected combinations before matching continues.

Setting	Configuration key	Behavior
Prevent matching from address to address (Default: off)	`prevent_address_to_address_matching`	Removes combinations where both pickup and drop-off would use the requested address instead of a station.
Prevent matching from address to address unless one of the requested points (origin/destination) is at a validated user location (Default: off)	`prevent_address_to_address_matching_at_unvalidated_location`	Removes address-to-address combinations unless the requested origin or destination is linked to a validated user location. If Prevent matching from address to address is also enabled, that broader setting still removes all address-to-address combinations.
Prevent address exact matching for the destination unless it is at a validated user location (Default: off)	`prevent_destination_address_matching_at_unvalidated_location`	Removes combinations where the drop-off would use the requested destination address unless that destination is linked to a validated user location. Station-based drop-off combinations can still be considered if the matching mode allows them.
Prevent address exact matching for the origin unless it is at a validated user location (Default: off)	`prevent_origin_address_matching_at_unvalidated_location`	Removes combinations where the pickup would use the requested origin address unless that origin is linked to a validated user location. Station-based pickup combinations can still be considered if the matching mode allows them.
Prevent matching from station to station (Default: off)	`prevent_station_to_station_matching`	Removes combinations where both pickup and drop-off would use stations.

A validated user location is a user location whose Validated flag is enabled in Control Center. User-created locations are not validated automatically.
For regular ride creation, these filters can only recognize validated user locations if Preprocess ride requests with snapping user locations is enabled in Matching. Otherwise, the requested point is not linked to a user location for these checks.

These options can be combined, and each one restricts a specific leg of the match:

Prevent address exact matching for the origin unless it is at a validated user location. The pickup can use the exact requested address only when the origin is a validated user location. Otherwise the pickup uses a station.
Prevent address exact matching for the destination unless it is at a validated user location. The drop-off can use the exact requested address only when the destination is a validated user location. Otherwise the drop-off uses a station.
Prevent matching from address to address. A ride can never use the exact address for both the pickup and the drop-off, so at least one leg always uses a station. This option ignores validation.

When you combine them, each option keeps its own effect:

With both validation options on, a door-to-door ride (exact address at both the pickup and the drop-off) is possible only when both the origin and the destination are validated user locations.
Prevent matching from address to address blocks door-to-door in every case, even between two validated points. It does not restrict single-leg matching, which the two validation options still govern on their own.

These options only affect a leg whose matching mode already offers the exact address (Address or Hybrid). If a leg is address-only and its point is not a validated user location, no ride can be offered for that request.

Search space and performance

Considered stations (affects station based products only) (Default: 2x2; Min: 1x1; Max: 25x25; Step: 1): This parameter affects only station-based or hybrid matchings. It defines how many of the closest stations to a requested point (departure and/or arrival) are taken into account. 2x2 means, for example, that the two closest stations to the requested departure point and the two closest stations to the requested arrival point are considered by the matching algorithm. This applies only to the station-based part of the matching.
Max number of enclosed tasks (Default: 8; Min: 0; Max: 25; Step: 1): The maximum number of enclosed tasks determines how many tasks in a vehicle planning can occur between the pickup and dropoff tasks of a ride. If set to zero, pooling is disabled, as no additional passengers can be picked up. Note that this includes all types of tasks, not just pickup and dropoff tasks.

Boundary conditions

Minimum ride length (straight-line distance) (Default: 0 m; Min: 0 m; Max: 50 km): The minimum straight-line distance between departure and arrival point.
Maximum time deviation to request (Default: 45 minutes; Min: 0; Max: 12 hours; Step: 5 minutes): This defines how much the time for an offered ride is allowed to differ from the requested times of a passenger. If the maximum time deviation is set to one hour, and a passenger requests a ride starting “next Monday at 9 am,” the part of the matching core that generates solutions will deviate by a maximum of ±1 hour, i.e., between 8 am and 10 am. However, this does not mean that all possible rides within this range will be searched. The time boundaries are calculated without accounting for walking durations or boarding times at stations. If the ride is booked based on arrival time, the maximum time deviation is applied to the arrival time. See the settings for prebooking and ad hoc booking for more details. The Control Center dropdown goes up to 24 hours, but the model validation caps the value at 12 hours.
Maximum tolerable summed up walking durations (Default: 20 minutes; Min: 0; Max: 1 hour; Step: 1 minute): This defines how long a passenger can be expected to walk from the requested departure point to the pickup and from the dropoff to the requested arrival point. This is the total walking time—the time walking to the pickup point plus the time walking from the dropoff to the arrival.
Maximum tolerable walking duration to the pickup (Default: 15 minutes; Min: 0; Max: 1 hour; Step: 1 minute): Limits the calculated walking duration from the requested point to the pickup location.
Maximum tolerable walking duration to the dropoff (Default: 15 minutes; Min: 0; Max: 1 hour; Step: 1 minute): Limits the calculated walking duration from the requested point to the dropoff location.
Streak split buffer threshold (Default: 15 minutes; Min: 0; Max: 6 hours; Step: 5 minutes): Refer to the page on the streak split.
Threshold for time window collapsing (Default: 0 seconds; Min: -30 minutes; Max: 30 minutes; Step: 15 seconds): Every task in a vehicle planning has a given time window for the corresponding calculated point.

The earliest possible arrival time at a pickup point and the latest possible arrival time that still allows the following task to be reached in time together define the time window for a pickup task. If the calculated latest time is earlier than the earliest time, the time window collapses.

As the matching algorithm inserts the pickup and drop-off tasks into all possible positions within the considered task lists, the corresponding time windows are calculated. If any time window in the corresponding vehicle planning collapses because of these new tasks, that specific ordering is not considered further, because it would not be possible to fulfil all requirements.

However, a provider may know that, due to special circumstances, drivers are often faster than predicted by the routing adapters. In this case, this parameter can be set to a negative value, allowing negative time intervals up to that point and therefore considering the corresponding vehicle plannings.

A threshold for time window collapsing of 0 is not recommended, as the core system supports only second-level precision. Even when the boarding time is set to 0, it will internally take 1 second. To ensure proper functionality, set the collapsing threshold to at least -15 seconds. If you know that drivers typically take longer, or if you want to prevent delays, you can set this parameter to a positive value, which requests a minimum time for the window.

Quality of service and pooling

Allowed travel time in relation to direct travel time (Default: 160%; Min: 100%; Max: 600%; Step: 1%): This defines the maximum total ride duration as a percentage of the direct travel time. For example, 160% means that the passenger’s ride may take up to 60% longer than the direct route, subject to the absolute detour bounds below. The travel time of a ride offer is evaluated against the direct travel time, which is calculated using the product’s Routing Adapter for Ride Direct Routing as defined in the Routing Setup. Higher values allow greater detours, which can increase pooling and enable more flexible matching; lower values prioritize individual passenger preferences. The model validation allows up to 1000%, but the Control Center dropdown stops at 600%.

If direct routing results in a 10-minute drive, and this parameter is set to 120%, the passenger must accept a ride duration of up to 12 minutes.

Minimum tolerable timely detour (Default: 10 minutes; Min: 0; Max: 6 hours; Step: 5 minutes): The lower bound on how much extra time a passenger’s ride can take compared to the direct route. In the model, the value must not be higher than Maximum tolerable timely detour, and the model allows values up to 24 hours.
Maximum tolerable timely detour (Default: 30 minutes; Min: 0; Max: 6 hours; Step: 5 minutes): The upper bound on how much extra time a passenger’s ride can take compared to the direct route. In the model, the value must not be lower than Minimum tolerable timely detour, and the model allows values up to 24 hours.

The Minimum tolerable timely detour and Maximum tolerable timely detour provide lower and upper bounds for the detour derived from Allowed travel time in relation to direct travel time. In simplified terms, ioki Platform calculates the percentage-based detour as (factor - 100%) x direct travel time, then limits that detour to the configured minimum and maximum. This matters because a purely percentage-based calculation would be a problem for very short and very long rides.

If “allowed travel time in relation to direct travel time” is set to 120%, the direct routing results in a ten-minute ride, and “minimum tolerable timely detour” is set to 5 minutes, this can result in a ride of up to 15 minutes, not 12. The percentage-based detour would be only 2 minutes, so the 5-minute minimum detour applies.

If “allowed travel time in relation to direct travel time” is set to 150%, the passenger must accept detours of up to 50% of the direct travel time. A 10-minute ride can therefore become 15 minutes long, but a 100-minute ride could also involve a possible detour of 50 minutes. If “minimum tolerable timely detour” is set to 5 minutes and “maximum tolerable timely detour” is set to 15 minutes, the long ride is capped at a 15-minute detour instead of the percentage-based 50-minute detour.

Minimum time window for pickup (Default: 5 minutes; Min: 0; Max: 2 hours; Step: 1 minute): This determines how much the time window at the passenger’s pickup can vary. If the value is small, the system tries to avoid making the passenger wait too long. If it is larger, the system can use that time to optimize pooling and other matching targets. This flexibility does not override other settings or configuration constraints.

If minimum time window for pickup is set to 5 minutes and the passenger receives confirmation for a ride at 12:00, the system can decide to make the passenger wait for 4 minutes, because the allowed window is up to 5 minutes. Since the pickup still falls within that 5-minute window, the passenger receives a pickup time of 12:04.

If the value is too small, optimization gains are limited. Values below ~5 minutes can prevent feasible ride combinations, as the system attempts to serve passengers at an exact time, blocking pooling with nearby pickups or dropoffs. If the value is too large, passengers may perceive poor service quality. Setting this to just a few minutes is recommended.

Solver weights

As explained in matching, all possible solutions that survive the filter stages, where boundary conditions and hard thresholds are enforced, are scored. The matching with the highest score is then offered to the passenger. This is done by penalizing unwanted behavior, such as long waiting times, and rewarding desired behavior, such as pooling.

Each weight is a multiplier. During scoring it is multiplied by the quantity it applies to—for most weights, a number of seconds (for example, seconds of waiting or driving). The results are summed into a single score that starts at 0: penalties are subtracted and gains are added, and the solution with the highest resulting score wins. A weight of 0 disables that term. Because the weights are relative to one another, only their ratios matter—scaling every weight by the same factor leaves the ranking unchanged.

Weights can be positive or negative. Most are per-second multipliers; the exceptions are noted below—for example, Gain points for :task_reuse is awarded once per reused task, and Penalty for :cost_benefit_ratio is applied to a unitless ratio.

Classical solver weights

Penalty per second driving time (driver) (Default: 0.5): The weight of the penalization multiplied by each second a driver spends driving.
Penalty per second waiting time (passenger) (Default: 1.0): The weight of the penalization multiplied by each second a passenger spends waiting. Waiting is the difference between the requested time for a task (pickup or dropoff) and the calculated time of the planning list; the absolute difference is used.
Penalty per second walking time (passenger) (Default: 1.2): The weight of the penalization multiplied by each second a passenger spends walking.
Gain points per second usage time (driving seconds x number of passengers) (Default: 0.0): The weight of the reward for capacity utilization—it rewards pooling. Use with caution: this can cause “hostage cases,” where passengers are kept in vehicles longer than necessary.
Penalty per second delay time (delay seconds x number of passengers) (Default: 1.0): The weight of the penalization of the delays of other passengers of the corresponding vehicle planning. Rides are never re-planned outside the negotiated time window, but delay within these windows can be penalized.

If the Penalty per second waiting time (passenger) is set to 2 and the Penalty per second driving time (driver) is set to 1, the passenger’s waiting time is penalized two times more than the driver’s driving time.

Advanced solver weights

The configuration also includes additional solver weights. These are more specific than the classical solver weights and can therefore have a stronger impact. They should be used instead of the classical solver weights—mixing them could lead to double penalties for the same factors.

Penalty for :driving_duration (Default: 0.0): Penalizes every second the vehicle is driving, regardless of whether passengers are on board.
Penalty for :empty_duration (Default: 0.0): Penalizes every second the vehicle is driving without any passengers on board.
Gain points for :loaded_duration (Default: 0.0): Rewards every second the vehicle is driving with at least one passenger on board.
Gain points for :ride_duration (Default: 0.0): Rewards ride-seconds across all active rides. If two rides overlap for one second, that second counts twice.
Gain points for :task_reuse (Default: 300.0): Rewards options where a pickup or dropoff can reuse a neighboring task. The score adds this value once per reused pickup or dropoff task. A task counts as reused if it is less than 15 meters and less than 5 minutes from the neighboring task.
Gain points for :passenger_duration (Default: 0.0): Rewards passenger-seconds. If three passengers stay on board for one second, that second counts three times.
Gain points for :passenger_direct_routing_duration (Default: 0.0): Rewards the total direct routing duration requested by passengers, counted per passenger.
Penalty for :additional_driving_duration (Default: 0.0): Penalizes the extra driving duration compared with the reference task list.
Penalty for :additional_empty_duration (Default: 0.0): Penalizes the extra empty driving duration compared with the reference task list.
Gain points for :additional_loaded_duration (Default: 0.0): Rewards the extra loaded driving duration compared with the reference task list.
Gain points for :additional_ride_duration (Default: 0.0): Rewards the extra ride-seconds compared with the reference task list.
Gain points for :additional_passenger_duration (Default: 0.0): Rewards the extra passenger-seconds compared with the reference task list.
Penalty for :additional_free_buffer_fragmentation (Default: 1.0): Penalizes additional fragmented free-buffer seconds compared with the reference task list. In ioki Platform, this metric sums cached free-buffer values below 300 seconds, including negative values.
Gain points for :additional_passenger_direct_routing_duration (Default: 0.0): Rewards the extra direct routing duration requested by passengers, counted per passenger, compared with the reference task list.

Penalty for :cost_benefit_ratio (Default: `0.0`)

This penalty can be used with both the classical and advanced solver weights. It helps determine whether adding an extra ride to a task list provides more benefit or incurs more cost for the service. The calculation considers:

Cost. The additional driving time the extra ride adds to the vehicle planning, found by comparing the vehicle’s total driving duration with and without the new ride.
Benefit. The additional direct routing duration the extra ride brings—effectively that ride’s own direct route, from the requested pickup to the requested dropoff.

By comparing ride durations with and without the extra ride, this penalty encourages efficient pooling and helps reduce unprofitable empty duration. In practice, setting this higher encourages pooling.

The duration is measured in time rather than distance (kilometers).

Routing overrides

A matching configuration can override the product’s routing setup. It can override the product defaults for time coefficient for vehicle routing and time coefficient for pedestrian routing, and for avoid U-turns. A cascading configuration model is used: if an override is enabled, that setting is used; if not, it falls back to the product’s routing setup.

Routing overrides allow fleet segmentation. For example, specific vehicle plannings can be assigned to a matching configuration that overrides the default time coefficient set at the product level.

Override product default for ‘Time coefficient for vehicle routing’
A separate matching configuration can be created for specific groups of drivers—such as inexperienced drivers who may drive more slowly—or for vehicles that typically operate at lower speeds, like rickshaws. In that matching configuration, a higher time coefficient for vehicle routing could be applied compared to the one set in the product settings.

Lead time

If the lead time product feature is activated, lead-time settings can be defined per matching configuration.