Routes

A route is a sequence of coordinates on the map. It represents the path the user must follow to get from point A to point B. The route may contain intermediate via points.

But the route contains more information than just the directions. For example, there are road warnings, the distance, and the estimated arrival time.

In MapKit SDK, the route is represented by the DrivingRoute class. Here are its main functions.

MetadataMetadata

DrivingRouteMetadata contains the route description, parameters, characteristics, distance, and estimated arrival time.

To get the metadata, use the DrivingRoute.metadata method.

Route URIRoute URI

URI is the route's string ID.

To get the route URI, use the DrivingRouteMetadata.uri method.

PositionPosition

The route may contain information about the current user position. It shows how much of the route has been completed during guidance.

To get the current position, use the DrivingRoute.position method.

Warnings and eventsWarnings and events

Road events provide information about traffic events along the route. To get information about road events along the route, use the DrivingRoute.events method.

Route warnings contain information about objects along the route. The objects include traffic lights (DrivingRoute.trafficLights), railway crossings (DrivingRoute.railwayCrossings), and speed bumps (DrivingRoute.speedBumps). Learn more in the DrivingRoute API.

Traffic jams on the routeTraffic jams on the route

Using the DrivingRoute.jamSegments you can get information about traffic congestion on the route. This method returns a list of JamSegment objects. Each element of the list describes the state of congestion of the road and the average speed of movement along it on the corresponding segment of the route. The segment with the number N corresponds to the section of the route that is located between N and N + 1 points of the route geometry, which can be obtained by calling DrivingRoute.geometry.

Subscribe to updatesSubscribe to updates

Some route data may change during the route life cycle. With MapKit SDK, you can track route data changes using the DrivingConditionsListener interface.

Calculation of progress along the routeCalculation of progress along the route

The progress along the route is the fraction of the original route that was completed.

Below is a code snippet for calculating this value:

double routeProgress(DrivingRoute route) {
  const startPosition = PolylinePosition(segmentIndex: 0, segmentPosition: 0.0);
  final distanceFull = route.metadataAt(startPosition).weight.distance.value;
  final distanceLeft = route.metadata.weight.distance.value;
  return 1.0 - distanceLeft / distanceFull;
}

To calculate the proportion of the route traveled, you need to calculate the total and the distance traveled of the route, and then divide one value by another.

Distance between route pointsDistance between route points

To calculate the distance between any two route points, use the PolylineUtils methods. Follow these steps:

1. Create a PolylineIndex object that's linked to your route using PolylineUtils.createPolylineIndex.

2. Use the PolylineIndex.closestPolylinePositionWithPriority method to get the route points PolylinePosition.

3. Calculate the distance between two route points using PolylineUtils.distanceBetweenPolylinePositions.

Here's an example of how to calculate the distance between two arbitrary route points:

double distanceBetweenPointsOnRoute(DrivingRoute route, Point first, Point second) {
  final polylineIndex = PolylineUtils.createPolylineIndex(route.geometry);

  final firstPosition = polylineIndex.closestPolylinePositionWithPriority(
    first,
    PolylineIndexPriority.ClosestToRawPoint,
    maxLocationBiast: 1.0
  )!;

  final secondPosition = polylineIndex.closestPolylinePositionWithPriority(
    second,
    PolylineIndexPriority.ClosestToRawPoint,
    maxLocationBiast: 1.0
  )!;

  return PolylineUtils.distanceBetweenPolylinePositions(route.geometry, firstPosition, secondPosition);
}

Time between route pointsTime between route points

Let's look at the algorithm for calculating the travel time from the current route point to an arbitrary later route point.

1. We need to calculate the distance between the current and next route points. To do so, we can use the algorithm from the previous step.

2. Using the RoutePosition.advance method, calculate RoutePosition for the second point.

3. Using the RoutePosition.timeToFinish method, find the travel time difference between the current and next points.

Here's an example of how to calculate the travel time from the current route point to another arbitrary route point:

double timeTravelToPoint(DrivingRoute route, Point point) {
  final currentPosition = route.routePosition;
  final distance = distanceBetweenPointsOnRoute(route, currentPosition.point, point);
  final targetPosition = currentPosition.advance(distance);
  return targetPosition.timeToFinish() - currentPosition.timeToFinish();
}

To calculate the travel time between any two route points, use the difference between the results of calculating their timeTravelToPoint.