The map matching component is responsible for determining where on the map to place the vehicle.

Visually, it offers a cleaner user experience than displaying a raw GNSS location from the platform: It can ‘snap’ the chevron to the centerline of the road being driven, correct for inaccuracies in weak or unreliable signal strength, and smooth over discrepancies between the real world and the map being used to navigate.

Functionally, it performs the vital role of translating raw location information to data that is usable in the wider navigation context and the known road network. It determines where on the map the user is. As such, it is necessary for knowing, for example, what the speed limit is or whether the user has deviated from their planned route. Downstream components also use this map-matched result to determine all sorts of navigation-related information, such as how much traffic there is on the current route, what the ETA is, and so on.

Map matching APIs - what is exposed & how to use it

This page should help you understand how the map matcher works under the hood, and what behavior you can expect in various situations. Much of the functionality of the map matcher affects downstream components, such as displaying the chevron or triggering route planning. The API surface of the component itself is limited - but if you’re interested in setting up your own component to consume a MapMatchingResult - this is how the pipeline works & how to do it.

1. Location updates are sent by an implementation of the LocationProvider interface. For setting this up, refer to the Location Quickstart guide . For most applications we recommend an update rate of 1 Hz, meaning we expect to receive and process one location update per second. Ideally, updates should not be sent at a frequency below 1 Hz. Higher update rates may be supported, though this is also subject to hardware limitations. For UI applications 1 Hz should be sufficient, as we interpolate between updates to render smooth, continuous progress.
2. As the platform passes raw location updates through the LocationProvider, you can listen for their map-matched counterparts by adding listeners. To do this, use the addLocationMapMatchedListener() and removeLocationMapMatchedListener() methods in TomTomNavigation . These methods add or remove a LocationMapMatchedListener , respectively.
3. The listener is notified of a new MapMatchingResult each time a location change occurs and the map matching component successfully matches it.
4. The LocationMapMatchedListener is a functional interface and invokes the method specified by onLocationMapMatched each time it is notified.

Scenarios - when and why does map matching get it wrong sometimes

If only using GNSS, map matching can be impacted by several challenges that may lead to a decrease in matching quality. Incorrect matches are more likely to happen when the following factors are true:

The user is not driving on a well-mapped highway or secondary road, or the road does not allow motorized vehicles.

The map matcher filters out or strongly reduces the likelihood of matching to undrivable or restricted roads, so that, for example, it doesn’t display a car driving on a pedestrian path or in bicycle lanes.

It can also occur that a lesser-used road is simply not known to the map - and a road must be present on the map in order for the map matcher to match to it. Aside from lesser-known roads, this may also happen on newly constructed roads or outdated maps, where the user is treated as if they are not driving on any road - or they may be matched to an incorrect nearby road instead. Issues could also be caused by a road’s geometry not being accurately presented on the map (e.g., the representation does not match the actual shape of the road, or a segment is missing) - this is also more common on lesser-used roads.

The user is driving in a dense urban environment, where the view of the sky is obstructed.

In open-air scenarios, satellites can get a better fix on the vehicle’s position: more satellites can be used to calibrate the result, and the signal from each satellite will not ‘bounce’ around (and off buildings) as much - leading to a more accurate reading.

The user is driving somewhere with a complex road network, or on one of two parallel roads.

Even the best positioning system have some inaccuracies or signal drift. This means the map matcher often relies on inaccurate data to make an informed decision about where the user might be. When there are many roads near the user, there are more opportunities for the map matcher to pick the wrong candidate. However, the component does have a few strategies to correct its estimation: for example, it can rely on the shape or speed limit of a road to see which matches the user’s trajectory and speed best. This will often be more reliable than just trusting latitude & longitude coordinates alone. In the case of parallel roads, it is harder to rely on this strategy, which is why incorrect positioning is more likely in such scenarios.

The user deviates from the route they have planned, or is expected to perform special maneuvers.

The map matcher makes several assumptions about user behavior and intent. For example, it assumes that if a user has a route planned, they planned it deliberately and so intend to follow it. For more on the algorithm behind this, see the section Deviation detection - when do we match the user off route . Likewise, the matcher assumes the user will generally not perform illegal maneuvers (such as U-turns where none are allowed, or driving the wrong way down a one-way street) - and will be strongly biased towards these conclusions.

When multiple of these criteria apply, performance may begin to degrade as it becomes harder to definitively determine a user’s position. In these cases, map matching algorithms attempt to mask the ambiguity or inaccuracy of data received and reduce the impact on the user.

Software dead reckoning - what happens when we have no GNSS input

One algorithm that helps reduce the impact of bad data on the user is software dead reckoning. It is activated whenever GNSS input is lost — for example, when the user drives into a tunnel, or in any other situation with poor GNSS signal reception that causes multiple location updates to be missed.

In the tunnel case, the map matcher will advance the chevron along its previous course to provide the user with a seamless driving experience: gradually speeding up or slowing down the user’s last known speed to match the traffic free-flow speed of that tunnel. If the estimation is done correctly, the user should experience the chevron traveling through the tunnel at roughly the same speed as their vehicle is actually traveling. If they are slower than the estimation, the chevron may ‘pause’ at the end of the tunnel; if they are faster, it may ‘skip’ ahead to the end of the tunnel when the user reaches it and the GNSS signal is regained. Generally, the estimation is accurate enough that the user won’t notice a difference.

When the algorithm is activated outside a tunnel, it works almost the same. The main difference is that it runs for at most 30 seconds — whereas in a tunnel, it can stay active for longer. In a tunnel, it remains active until the tunnel ends and signal is regained.

Within the SDK, you can check whether a position was provided by software dead reckoning ( SoftDR ) by accessing the LocationProviderType - available at matchedLocation.location.providerType in the MapMatchingResult that is emitted to a LocationMapMatchedListener .

Probability & map data availability - when do we match the user off-road

Because the map matcher deals with unreliable input data, the MatchedLocation contains a probability value to reflect the confidence level. If the map matcher cannot determine the road that the user is actually driving on with a high enough degree of confidence - or if the user is not driving on any road at all - the match is marked as off-road. A Boolean called isOnRoad reflects this in the MatchedLocation . This may happen, for example, when driving on paths, private roads, newly constructed highways, or parking lots that have not (yet) been added to the map. However, it can also happen when map data is altogether unavailable — for example, when a user has an online-only map configuration, no internet connectivity, and no pre-downloaded/cached map data to fall back on.

When a user is off-road, certain data may be unavailable (such as speed limits), and visually they will be shown the raw location input coordinates and heading received from the GNSS signal.

Deviation detection - when do we match the user off-route

The map matcher assumes that when a user plans a route, it is their general intent to follow it. Nevertheless, it should be possible for the user to deviate from their planned route - perhaps they, for example, trust their local knowledge over the route recommended by the navigation service, or they deviate unintentionally by accidentally missing an exit or instruction. This presents a trade-off problem: we want to respond quickly enough when a user has actually deviated, but also filter out unreliable signal input that suggests a deviation when one hasn’t actually occurred.

As such, the map matcher has an inbuilt route attraction - a form of bias or stickiness to the route - to decide when to match to a road that is not part of the route and when to continue along the planned route. The strength of this bias is not externally configurable and has been extensively fine-tuned by balancing user experience in each scenario, as well as additional data consumption considerations.

When the input signal can be trusted more, we reduce this route attraction bias. To improve the trustworthiness of the GNSS signal, integrators can provide additional data to the SDK from other sensors that their platform supports.