FAQs

Yes, the events and gestures of the SDK can be customized.

By default, the map supports the following gestures:

• Panning.
• Zooming in and out.
• Rotating.
• Tilting.

The map component provided by the TomTom Map Display module reacts to these gestures with predefined behaviors, but the gesture handling and interactions can be customized depending on the application requirements.

A route deviation is detected and updated as soon as map matching deviates from the planned route.

Typically, the route is updated within a matter of seconds.

A deviation is triggered when:

• The user is off-route for approximately 30-100 meters, depending on the road importance and driving conditions. In most cases, route deviation is detected much sooner, while on highways or major roads it may require a greater distance before rerouting is triggered.
• The user skips a waypoint but still follows the road geometry. For example, the user reaches an intersection where they should turn left, visit a waypoint, and make a U-turn to return to the same intersection. If the user turns right instead, they are technically still following the expected road geometry, but since the waypoint was skipped, a deviation is triggered.

Yes. When navigation is used without a planned route, it is called free driving.

Free driving provides detailed information about the current location, including:

• Speed.
• Speed limit.
• Street name.
• Road characteristics.
• Hazards.
• Safety-related road information such as speed cameras.
• Country code.

Yes. Route progress is available as soon as navigation starts and is updated on every location update, roughly once per second, for the active route.

Once navigation starts, you can listen for those updates to check the route progress: set ProgressUpdatedListener to the TomTomNavigation object . The ProgressUpdatedListener is triggered whenever the user’s progress along the Route changes.

These provide the current RouteProgress, which contains:

• the arrival time,
• the remaining time,
• the remaining distance along the route,
• same data for the unvisited route stops,

The ETA, or arrival time, is not provided directly as a direct field. It can be derived by adding the remaining time to the current system time.

Yes. The SDK supports three unit systems: Metric (meters and kilometers), US (miles and feet), and UK (miles and yards). By default, the unit system is resolved from the device’s locale settings.

The unit system for navigation controls how guidance announcements and distance displays are formatted. It is configured on TomTomNavigation via its configuration property, which exposes a mutable unitSystem of type UnitSystemType.

For an implementation example, check the tomtom-example-app.

No, the SDK does not provide a built-in UI component to render signposts.

However, it exposes some signpost-related data that can be used to build custom UI. This includes information such as exit icons, road shields, road numbers, and road names.

To access this data, enable extended guidance sections on GuidanceOptions when building RoutePlanningOptions to plan a route: GuidanceOptions(extendedSections = ExtendedSections.All).

Once the route has been successfully planned, a Route object is returned. This object exposes a Sections property that groups all section types for the route. To access signpost data, use route.sections.roadShieldSections, which returns a list of RoadShieldSection. Each section covers a segment of the route and contains a list of RoadShieldReference objects.

These sections provide references to road shields together with their associated content, which can include visual identifiers such as route numbers or exit-related information that can be used to build custom guidance experiences.

Yes. When you build the route options, set the avoids property to a set of AvoidType values that the routing engine should keep out of the route. To exclude Low Emission Zones, include AvoidType.LowEmissionZones:

1
val amsterdam = GeoPoint(52.377956, 4.897070)
2
val rotterdam = GeoPoint(51.926517, 4.462456)
3
val routePlanningOptions = buildRoutePlanningOptions(
4
    itinerary = Itinerary(origin = amsterdam, destination = rotterdam),
5
    avoids = setOf(AvoidType.LowEmissionZones),
6
)

You can list several avoid criteria in the same set, and the engine applies all of them. Avoids are best effort (see “Are avoid options guaranteed?” below).

Learn more: Planning Routes (Avoids). For an implementation example, check the routing demo at the tomtom-example-app.

Yes. Every successfully planned route returns a Route object whose sections property groups the route data by type. Read route.sections.speedLimitSections to get a list of SpeedLimitSection, each giving the speed limit for a stretch of the route. The same sections object exposes related lists that share the route’s offset and length coordinate system, such as trafficSections, vehicleRestrictedSections, and laneSections. The complete-flavor builder requests these route sections for you, so they are populated on the planned route.

Learn more: Route Sections.

Yes. The SDK can reconstruct a route from a polyline you supply as a list of supporting points. Set the supportingPoints property on a RouteLegOptions instance and pass it to the route options through routeLegOptions. When supporting points are present, the engine matches the calculated route as closely as it can to those points. This is how you import a route from another source or reconstruct a previously driven path.

Learn more: Waypoints and Supporting Points, Polyline Reconstruction.

Yes. After a route is planned, each RouteLeg in the Route exposes an instructions property holding the ordered list of instructions for that leg. With the complete-flavor builder, guidance instructions are generated automatically, so route.legs.flatMap { it.instructions } gives the full ordered list for the trip. You can tune the phonetics with the builder’s instructionPhoneticsType setting.

While navigating, the SDK also emits guidance updates as the location changes, and each update carries the upcoming instructions.

Learn more: Planning Routes (Guidance instructions).

Yes. The planning time is set on the Itinerary through its planningTime property, which takes a PlanningTime:

• PlanningTime.DepartureTime(departureTime) plans a route that starts at a specific time.
• PlanningTime.ArrivalTime(arrivalTime) plans a route that reaches the destination by a specific time.
• PlanningTime.DepartNow plans from the current moment (the default).

1
val amsterdam = ItineraryPoint(Place(GeoPoint(52.377956, 4.897070)))
2
val rotterdam = ItineraryPoint(Place(GeoPoint(51.926517, 4.462456)))
3
val itinerary = Itinerary(
4
    origin = amsterdam,
5
    destination = rotterdam,
6
    planningTime = PlanningTime.DepartureTime(PlanningTime.NOW.plusHours(2)),
7
)
8
val routePlanningOptions = buildRoutePlanningOptions(itinerary = itinerary)

Once the route is calculated, the timing details are available on the summary property of the returned Route: travelTime (estimated travel time), departureTime (in the departure location’s time zone), arrivalTime (in the destination’s time zone), and trafficDelay (the additional time caused by traffic).

Learn more: Planning Routes (Planning time). For an implementation example, check the route with timing demo at the tomtom-example-app.

Yes. Hazardous materials restrictions come from the vehicle profile. When the vehicle is a Truck or a Van, you can declare the cargo it carries:

• hazmatClasses: a Set<HazmatClass> classifying the hazardous materials (for example UnClass3FlammableLiquid or UnClass7Radioactive).
• adrTunnelRestrictionCode: an AdrTunnelRestrictionCode (B, C, D, or E) controlling which tunnels the vehicle may enter.

With these set on the vehicle, the engine respects the road and tunnel restrictions that apply to the declared cargo.

Learn more: Planning Routes (Vehicle).

Set the routeType in the builder to choose the optimization strategy:

• RouteType.Fast: optimizes for the shortest travel time (the default).
• RouteType.Short: optimizes for the shortest distance.
• RouteType.Efficient: balances travel time and distance for lower fuel or energy use.
• RouteType.Thrilling(hilliness, windingness): prefers winding and hilly roads.

Fast, Short, and Efficient are available in the complete flavor.

Learn more: Planning Routes (Route type).

Yes. Electric vehicle routing is supported in the complete flavor through the buildEvRoutePlanningOptions builder, which takes the Itinerary and a ChargingOptions:

1
val amsterdam = GeoPoint(52.377956, 4.897070)
2
val rotterdam = GeoPoint(51.926517, 4.462456)
3
val chargingOptions = ChargingOptions(
4
    minChargeAtChargingStops = 5.kilowattHours,
5
    minChargeAtDestination = 10.kilowattHours,
6
)
7
val routePlanningOptions = buildEvRoutePlanningOptions(
8
    itinerary = Itinerary(origin = amsterdam, destination = rotterdam),
9
    chargingOptions = chargingOptions,
10
)

Set VehicleProvider.vehicle to a Vehicle.Car that has an electric engine so the builder plans for your EV. The engine inserts charging stops where needed so the destination stays reachable, and the resulting route carries the charging information (added stops, arrival charge, and charging details).

Learn more: Planning EV Routes. For an implementation example, check the long distance EV routing demo at the tomtom-example-app.

Yes. Set the builder’s maxAlternatives to request alternatives (a value from 0 to 2). The planning result returns a list of routes: the first is the main route, and any others are the alternatives, all available before navigation starts.

1
val amsterdam = GeoPoint(52.377956, 4.897070)
2
val rotterdam = GeoPoint(51.926517, 4.462456)
3
val routePlanningOptions = buildRoutePlanningOptions(
4
    itinerary = Itinerary(origin = amsterdam, destination = rotterdam),
5
    maxAlternatives = 2,
6
)

Learn more: Planning Routes with Alternatives.

Yes, for the Thrilling route type. RouteType.Thrilling accepts a Hilliness and a Windingness, each of which can be Low, Normal, or High. Hilliness controls how much the route favors elevation changes, and Windingness controls how much it favors curves. These options apply to the Thrilling route type and have no effect on the other route types.

Learn more: Planning Routes (Route type).

Set the builder’s avoids to a set of AvoidType values. The available values are:

TollRoads, Motorways, Ferries, UnpavedRoads, CarPools, AlreadyUsedRoads, BorderCrossings, Tunnels, CarTrains, and LowEmissionZones.

Add as many of these to the set as you need, and the engine applies all of them.

Learn more: Planning Routes (Avoids).

Yes. The route options carry a vehicle describing the vehicle, and the engine selects roads suited to that profile. For example, a heavy Truck is kept off roads with weight limits it would exceed, and its dimensions, weight, and cargo restrictions all influence the route.

Learn more: Planning Routes (Vehicle).

Create the planner with TomTomSdk.createRoutePlanner(). It returns a planner suited to the SDK configuration. When an onboard NDS map is configured, planning uses that map data on the device and works without connectivity. When no onboard map is configured, planning calls the TomTom Routing API, which needs a network connection and a valid API key.

Learn more: Quickstart.

The complete flavor covers everyday route planning through the buildRoutePlanningOptions and buildEvRoutePlanningOptions builders. Within those builders you can set maxAlternatives, routeType (Fast, Short, Efficient), avoids, language, and instructionPhoneticsType, and you control origin, destination, waypoints, and planning time through the Itinerary. The vehicle used by these builders is a Vehicle.Car set through the VehicleProvider singleton. Reading the planned route is also a complete-flavor capability, including its summary and its route sections (such as speedLimitSections and lowEmissionZoneSections).

The extended flavor adds further routing APIs. These unlock custom vehicle profiles set directly on the route options (trucks, vans, and hazardous materials), supporting points for custom routes, the Thrilling route type with hilliness and windingness, reachable range calculation, and the SectionType descriptors used to request specific section types.

When you build the options with the complete-flavor builder, guidance instructions are generated for you, so RouteLeg.instructions is populated. If you construct the route options directly in the extended flavor, instructions are generated only when you set guidanceOptions to a GuidanceOptions instance. When guidanceOptions is left unset in that case, the instruction lists are empty.

Learn more: Planning Routes (Guidance instructions).

No, they are best effort. The engine honors the avoid criteria whenever a reasonable route that satisfies all of them exists. When satisfying a criterion would force an excessive detour, the engine may route through an excluded area on parts of the route. You can detect these cases by inspecting the matching route sections on the planned route, for example route.sections.lowEmissionZoneSections or route.sections.tollSections. Reading these sections works in the complete flavor.

Learn more: Planning Routes (Avoids), Route Sections.

Yes. Use RangeCalculator.calculateRange(RangeCalculationOptions) to compute the reachable area from an origin. The result is a Range describing the boundary polygon. Budgets can be based on distance, time (an isochrone), fuel, or energy.

Learn more: Calculating Ranges.

Yes. Route.summary.travelTime accounts for traffic conditions. The summary also reports trafficDelay (the extra time from traffic) and trafficLength (the distance affected by traffic), so you can see how much of the travel time comes from traffic.

Route planning is asynchronous. The call returns a Cancellable so you can cancel an in-flight request, and it reports its outcome as a Result<RoutePlanningResponse, RoutingFailure>. On success, RoutePlanningResponse holds the planned routes. On failure, RoutingFailure identifies the cause. Common subtypes to handle include NoRouteFoundFailure, ApiKeyFailure, BadInputFailure, NetworkFailure, and ComputationTimeoutFailure.