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.getMetadata method.

Route URIRoute URI

URI is the route's string ID.

To get the route URI, use the DrivingRouteMetadata.getUri 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.getPosition 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.getEvents method.

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

Traffic jams on the routeTraffic jams on the route

Using the DrivingRoute.getJamSegments 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.getGeometry.

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 ConditionsListener 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:

fun routeProgress(route: DrivingRoute): Float {
    val startPosition = PolylinePosition(0.0, 0.0)
    val distanceFull = route.metadataAt(startPosition).weight.distance.value
    val distanceLeft = route.metadata.weight.distance.value
    return 1f - 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.closestPolylinePosition 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:

fun distanceBetweenPointsOnRoute(route: DrivingRoute, first: Point, second: Point): Float {
    val polylineIndex = PolylineUtils.createPolylineIndex(route.geometry)
    val firstPosition = polylineIndex.closestPolylinePosition(first, Priority.CLOSEST_TO_RAW_POINT, 1.0)!!
    val secondPosition = polylineIndex.closestPolylinePosition(second, Priority.CLOSEST_TO_RAW_POINT, 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:

fun timeTravelToPoint(route: DrivingRoute, point: Point): Float {
    val currentPosition = route.routePosition
    val distance = distanceBetweenPointsOnRoute(route, currentPosition.point, point)
    val 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.