NavigationService class abstract Routes & Navigation

Manage turn-by-turn navigation and simulation on routes.

Manages real-time navigation sessions using device GPS or simulated position data, delivering turn-by-turn guidance, waypoint notifications, and route recalculations. Supports both live navigation (using PositionService) and simulation modes for testing without GPS.

The NavigationService provides support for two primary modes:

  • Navigation: Uses real position data from PositionService. Requires GPS permissions and active position tracking. Automatically handles route deviations and recalculations.
  • Simulation: Follows route without GPS, using configurable speed multiplier. Ideal for testing and previewing navigation experience.

The usual workflow for navigation or simulation is:

  1. Calculate a valid navigable route using RoutingService.
  2. For navigation mode, configure PositionService with live or custom data source.
  3. Start the navigation or simulation session with startNavigation or startSimulation.
  4. Toggle automatic TTS instructions playback using SoundPlayingService.
  5. Optionally, set map camera to follow position with GemMapController.startFollowingPosition.

Common operations

  • Start/stop navigation or simulation sessions
  • Receive instruction updates, waypoint/destination notifications, TTS text
  • Query current route, instruction, status
  • Handle route recalculations and better route detection
  • Set temporary roadblocks or skip waypoints

Example

void onNavigationInstructionUpdated(NavigationInstruction instruction,
    Set<NavigationInstructionUpdateEvents> events) {
  final instructionText = instruction.nextTurnInstruction;
  // Update UI with instruction
}

void onDestinationReached(Landmark destination) {
  print("Arrived at ${destination.name}");
}

void onTextToSpeechInstruction(String textInstruction) {
  print("TTS Instruction: $textInstruction");
}

// Start navigation
TaskHandler? handler = NavigationService.startNavigation(
  route,
  onNavigationInstruction: onNavigationInstructionUpdated,
  onDestinationReached: onDestinationReached,
  onTextToSpeechInstruction: onTextToSpeechInstruction,
);

See also:

Constructors

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

simulationMaxSpeedMultiplier → double
Maximum simulation speed multiplier.
no setter
simulationMinSpeedMultiplier → double
Minimum simulation speed multiplier.
no setter
transferStatistics → TransferStatistics
Navigation transfer statistics.
no setter

Static Methods

cancelNavigation([TaskHandler? taskHandler]) → void
Active navigation session cancellation.
getBetterRouteTimeDistanceToFork({TaskHandler? taskHandler}) → TimeDistance
Better route fork point time and distance.
getDataSource(TaskHandler navigationListener) → DataSource
Navigation data source accessor.
getIntermediateWaypointDropParameters() → ParameterList
Intermediate waypoint drop parameters.
getNavigationInstruction({TaskHandler? taskHandler}) → NavigationInstruction?
Current navigation instruction.
getNavigationParameters() → ParameterList
Navigation configuration parameters.
getNavigationRoute({TaskHandler? taskHandler}) → Route?
Current navigation route.
isNavigationActive({TaskHandler? taskHandler}) → bool
Navigation session active status.
isSimulationActive({TaskHandler? taskHandler}) → bool
Simulation session active status.
isTripActive({TaskHandler? taskHandler}) → bool
Active trip status (navigation or simulation).
setNavigationRoadBlock(int length, {int startDistance = -1, TaskHandler? taskHandler}) → void
Temporary route roadblock configuration.
skipNextIntermediateDestination({TaskHandler? taskHandler}) → GemError
Next intermediate waypoint skip.
startNavigation(Route route, {void onNavigationInstruction(NavigationInstruction instruction, Set<NavigationInstructionUpdateEvents> events)?, void onNavigationStarted()?, void onTextToSpeechInstruction(String textInstruction)?, void onWaypointReached(Landmark landmark)?, void onDestinationReached(Landmark landmark)?, void onRouteUpdated(Route route)?, void onBetterRouteDetected(Route route, int travelTime, int delay, int timeGain)?, void onBetterRouteRejected(GemError reason)?, void onBetterRouteInvalidated()?, void onSkipNextIntermediateDestinationDetected()?, void onTurnAround()?, void onError(GemError error)?, void onNotifyStatusChange(NavigationStatus status)?, void onRouteCalculationStarted()?, void onRouteCalculationCompleted(GemError error)?}) → TaskHandler?
Real-time GPS navigation session.
startSimulation(Route route, {void onNavigationInstruction(NavigationInstruction instruction, Set<NavigationInstructionUpdateEvents> events)?, void onNavigationStarted()?, void onTextToSpeechInstruction(String textInstruction)?, void onWaypointReached(Landmark landmark)?, void onDestinationReached(Landmark landmark)?, void onRouteUpdated(Route route)?, void onBetterRouteDetected(Route route, int travelTime, int delay, int timeGain)?, void onBetterRouteRejected(GemError reason)?, void onBetterRouteInvalidated()?, void onSkipNextIntermediateDestinationDetected()?, void onTurnAround()?, void onError(GemError error)?, void onNotifyStatusChange(NavigationStatus status)?, void onRouteCalculationStarted()?, void onRouteCalculationCompleted(GemError error)?, double speedMultiplier = 1.0}) → TaskHandler?
Simulated navigation session.
updateNavigationSound(TaskHandler navigationListener) → void
TTS instruction update request.