Matching parameters
Roles: Super Admin
In the Matching parameters section in the management settings of a product, you can configure the matching algorithm.
Search space and performance
Matching max rounds
This setting limits how many matching rounds ioki Platform can run for one request.
The planning-list builder orders candidate batches so that solutions that are likely to be closer to the requested time are tried first. Another round starts only if the current round does not produce a valid solution and more batches are still available.
This setting is a maximum, not a promise that every request will be split into that many rounds. If the search space is small enough, the first round can already consume all candidates. Higher values let matching continue further through the search space, but they can also increase matching time.
Matching target batch size per round
This setting defines the preferred number of planning lists that should be processed in one matching round.
The value is a target, not a guaranteed exact batch size. Larger batches give the algorithm more alternatives per round, but they also increase routing work and can slow matching down. Smaller batches reduce work per round, but they can lead to more rounds and earlier stopping on a less suitable solution.
Matching min batch size per round
This setting defines the minimum size of the last batch in a matching round.
If the remaining planning lists would form a smaller final batch, ioki Platform merges that remainder into the previous batch instead of processing a very small batch on its own. This means the actual number of rounds can be lower than matching max rounds. Use this setting together with matching target batch size per round.
How matching rounds work in practice
Matching rounds do not create fixed time windows such as
-15/+15, then-30/+30, then-45/+45.ioki Platform first builds and sorts planning-list candidates, then groups them into batches. The number of actual rounds depends on how many candidates exist, how large the batches are, and whether a valid solution is already found in an earlier batch.
In a small search space, the first round can already consume all candidates. In a large search space, later batches can extend the search further. Very small trailing batches can also be merged into the previous batch, so the actual number of rounds can stay below the configured maximum.
Read matching max rounds as an upper limit, not as a guarantee that every request will always be split into that many neatly separated rounds. For the broader effect on passenger-facing offers, see Extended search space.
Matching fingerprint subsampling steps
This setting defines how many time-shifted variants are created for each matching fingerprint.
The variants are created symmetrically around the unshifted candidate. A value of 1 keeps only the unshifted variant. A value of 2 creates three variants, and a value of 4 creates seven.
This increases the number of temporal variants that can be compared for the same structural insertion, but it also increases the number of planning lists that need to be evaluated.
For departure-based requests, the offset is applied to the pickup side of the request. For arrival-based requests, it is applied to the dropoff side.
Matching fingerprint subsampling size
This setting defines the distance, in seconds, between neighbouring time-shifted variants created by matching fingerprint subsampling steps.
For example, if the size is 180, neighbouring variants are three minutes apart. Together with four subsampling steps, this produces offsets of -540, -360, -180, 0, 180, 360, and 540 seconds around the unshifted variant.
This setting changes how widely the algorithm explores time-shifted variants. It does not relax the final request constraints, and it does not create fixed time windows per round.
Considered vehicles
This parameter indicates the number of vehicle plannings that should be considered in the Task List Finder step of the matching algorithm.
Considered vehicles is not intended to include all available vehicles, but rather a reasonable subset that are likely to be in the area at the requested time. This parameter should not be adjusted in isolation and must be evaluated together with other settings, for example, considered stations (affects station based products only) and maximum time deviation to request.
Raising this value is possible but should be done gradually and monitored carefully. Setting considered vehicles too high can lead to:
- Longer matching times
- Higher request volumes to external services
Changes to this setting should therefore always be evaluated in the broader performance context.
Max number of high-quality routings
This setting determines how many different solutions should be routed with high-quality routing in the second pass of the time frame builder.
Max number of high-quality routings in analyze runs
This determines how many different solutions should be routed with high-quality routing in sampled analyze runs. This setting applies only if Prediction-based triage is enabled is selected.
Max number of persisted solutions
This represents the number of solutions that should be stored in the database.
Single iteration matching (skip low quality pass)
If this is checked, matching is done in a single iteration and only the high-quality routing adapters are used. This prevents matching from filtering out good solutions because of poor estimates in the low-quality run. However, it should be used with care because it introduces many matrix routing requests to the routing adapter and increases matching time.
Prediction-based triage is enabled
When this setting is enabled, ioki Platform runs an estimation-stage validation before the final validation. In that estimation stage, the system assumes best-case timings and can already filter out solutions that are unlikely to work.
At that stage, the validator can already reject solutions for errors such as not enough time, broken task-list order, time in the past, walking times that are too high, ride duration exceeded, time deviation exceeded, and opportunity cost too high. Checks that depend on exact calculated times are still evaluated only in the final validation.
For time deviation, an exact requested time uses the configured maximum time deviation. Hard earliest and latest request times remain hard bounds.
Probability of making a matching run with analyzing feature enabled
To control prediction-based triage, ioki Platform can occasionally run a sampled analyze run to check whether a working solution would otherwise have been filtered out too early.
In an analyze run, estimation-stage errors are recorded, but they do not eliminate the solution at that stage. The ride request becomes an analyze run with this probability.
Boundary conditions
Time deviation threshold on match appliance
This setting is a tolerance limit that validates whether the actual pickup and dropoff times for a ride, once calculated and applied after a driver accepts the ride, remain within an acceptable deviation from the times that were negotiated during the matching phase. Its default is 15 minutes.
When a driver accepts a precalculated matching solution, the system creates actual tasks with specific times; if those actual times deviate from the negotiated times by more than this threshold, the application is rejected and the ride is marked as failed.