Driving Routing

This guide describes how to plan driving routes using the Navigation SDK. You can generate route plans based on a start point, destination, waypoints, and route calculation strategies.

Before You Begin

Before you start, familiarize yourself with the following core classes:

* AMapNavi: The navigation management class. It provides methods for route planning, pre-trip route selection, and rerouting during navigation. This class is a singleton. Obtain the instance using getInstance() and destroy it using destroy().

* AMapNaviListener: The protocol for navigation events and data. It provides callbacks for events during route calculation and navigation (e.g., route calculation success/failure, TTS strings, weak GPS signal, arrival at destination) and real-time data (e.g., guidance information NaviInfo, location information, electronic eye information).

Important Notes

* Route planning requires a network connection.

* Start and end points can be obtained in several ways, such as using the coordinate picker to query coordinates, or using the POI search in the Search SDK to find points of interest.

* As of Navigation SDK V5.0.0, you can set up to 16 waypoints. Note: The navigation component supports a maximum of 3 waypoints.

* Route calculation strategies include single-strategy and multi-strategy modes. With multi-strategy mode, the SDK can calculate multiple routes. Use the AMapNavi.getNaviPaths() method to retrieve these routes.

Step 1: Choose a Route Calculation Strategy

The Navigation SDK provides 21 driving strategies, which are divided into two types: strategies that return a single route and strategies that return multiple routes. These are defined in the PathPlanningStrategy enum.

Strategy Reference

Strategy ID	Constant Field	Description
0	DRIVING_DEFAULT	Speed priority. Ignores current traffic conditions. Returns the route with the shortest travel time, which may not be the shortest distance.
1	DRIVING_SAVE_MONEY	Cost priority. Avoids toll roads and selects the route with the shortest travel time.
2	DRIVING_SHORTEST_DISTANCE	Distance priority. Ignores traffic conditions. Returns the route with the shortest distance, which may pass through small roads or residential areas.
3	DRIVING_NO_EXPRESS_WAYS	Speed priority. Avoids expressways (e.g., Jingtong Expressway). Due to strategy iteration, using strategy 13 is recommended.
4	DRIVING_AVOID_CONGESTION	Avoids congestion. May result in detours and longer travel times.
5	DRIVING_MULTIPLE_PRIORITY_SPEED_COST_DISTANCE	Multi-strategy. Simultaneously uses speed priority, cost priority, and distance priority. Depending on traffic conditions, the SDK returns one to three route plans.
6	DRIVING_SINGLE_ROUTE_AVOID_HIGHSPEED	Speed priority. Avoids highways, but may still include other toll roads.
7	DRIVING_SINGLE_ROUTE_AVOID_HIGHSPEED_COST	Cost priority. Avoids highways and all toll roads.
8	DRIVING_SINGLE_ROUTE_AVOID_CONGESTION_COST	Avoids congestion and tolls. May include highways. Considers traffic conditions to avoid congestion, but may result in detours and longer travel times.
9	DRIVING_SINGLE_ROUTE_AVOID_HIGHSPEED_COST_CONGESTION	Avoids congestion and tolls. Does not use highways.
10	DRIVING_MULTIPLE_ROUTES_DEFAULT	Returns results that avoid congestion, have a shorter distance, and aim to reduce travel time. This is consistent with the default strategy of the AMAP app (i.e., no checkboxes selected).
11	DRIVING_MULTIPLE_SHORTEST_TIME_DISTANCE	Returns three results: shortest time, shortest distance, and avoid congestion. Due to better algorithms, using strategy 10 is recommended.
12	DRIVING_MULTIPLE_ROUTES_AVOID_CONGESTION	Returns results that consider traffic conditions and aim to avoid congestion. This is consistent with the "Avoid Congestion" strategy in the AMAP app.
13	DRIVING_MULTIPLE_ROUTES_AVOID_HIGHSPEED	Returns results that avoid highways. This is consistent with the "Avoid Highways" strategy in the AMAP app.
14	DRIVING_MULTIPLE_ROUTES_AVOID_COST	Returns results that aim for lower or no toll costs. This is consistent with the "Avoid Tolls" strategy in the AMAP app.
15	DRIVING_MULTIPLE_ROUTES_AVOID_HIGHSPEED_CONGESTION	Returns results that consider traffic conditions, avoid congestion, and avoid highways. This is consistent with the "Avoid Congestion & Avoid Highways" strategy in the AMAP app.
16	DRIVING_MULTIPLE_ROUTES_AVOID_HIGHTSPEED_COST	Returns results that aim to avoid highways and plan routes with lower or no toll costs. This is consistent with the "Avoid Tolls & Avoid Highways" strategy in the AMAP app.
17	DRIVING_MULTIPLE_ROUTES_AVOID_COST_CONGESTION	Returns results that aim to avoid congestion and plan routes with lower or no toll costs. This is consistent with the "Avoid Congestion & Avoid Tolls" strategy in the AMAP app.
18	DRIVING_MULTIPLE_ROUTES_AVOID_HIGHSPEED_COST_CONGESTION	Returns results that aim to avoid congestion, plan routes with lower or no toll costs, and avoid highways. This is consistent with the "Avoid Congestion & Avoid Tolls & Avoid Highways" strategy in the AMAP app.
19	DRIVING_MULTIPLE_ROUTES_PRIORITY_HIGHSPEED	Returns results that prioritize highways. This is consistent with the "Highway Priority" strategy in the AMAP app.
20	DRIVING_MULTIPLE_ROUTES_PRIORITY_HIGHSPEED_AVOID_CONGESTION	Returns results that prioritize highways and consider traffic conditions to avoid congestion. This is consistent with the "Avoid Congestion & Highway Priority" strategy in the AMAP app.

Using the Strategy Converter

You can use the strategy IDs from the table above directly. To replicate the checkbox-based strategy selection in the AMAP app, use the strategyConvert method in AMapNavi.

Method

Parameters

Return Value

Description

Notes

strategyConvert

avoidCongestion: Whether to avoid congestion.

avoidHighway: Whether to avoid highways.

avoidCost: Whether to avoid tolls.

prioritiseHighway: Whether to prioritize highways.

multipleRoute: Single or multiple routes. This parameter is deprecated since version 6.3; multi-route calculation is used by default.

int

Converts the specified rules into a PathPlanningStrategy enum value.

avoidHighway and prioritiseHighway cannot both be true.

prioritiseHighway and avoidCost cannot both be true.

Step 2: Calculate a Route

You can calculate a driving route using coordinates, POI information, or a start angle.

Calculate a Route by Coordinates

Pass the latitude and longitude of the start and end points.

// Get the navigation manager
AMapNavi mAMapNavi = AMapNavi.getInstance(this);

// Start point
List<NaviLatLng> startList = new ArrayList<NaviLatLng>();
startList.add(new NaviLatLng(39.993308, 116.473199));

// End point
List<NaviLatLng> endList = new ArrayList<NaviLatLng>();
endList.add(new NaviLatLng(39.917834, 116.397036));

// Calculate the route
mAMapNavi.calculateDriveRoute(startList, endList, null, PathPlanningStrategy.DRIVING_MULTIPLE_ROUTES_DEFAULT);

Calculate a Route by POI

Pass the POI information of the start and end points. You can obtain POI information using the POI search service provided by the AMAP Platform.

AMapNavi mAMapNavi = AMapNavi.getInstance(this);

// Start point
NaviPoi start = new NaviPoi("Longcheng Garden", null, "B000A8UF3J");

// End point
NaviPoi end = new NaviPoi("Peking University", null, "B000A816R6");

// Calculate the route
mAMapNavi.calculateDriveRoute(start, end, null, PathPlanningStrategy.DRIVING_MULTIPLE_ROUTES_DEFAULT);

Note: The NaviPoi object can also accept latitude and longitude coordinates. The POI ID takes priority. If the POI ID is invalid, the SDK uses the coordinates for route calculation.

Calculate a Route with a Start Angle

When using POI-based route calculation, you can specify a custom start angle for the start point via the NaviPoi object. This allows the SDK to plan a route that is appropriate for the given departure direction.

Important: To use a custom start angle, do not provide a poiId. You must provide latitude and longitude coordinates and a valid angle value.

AMapNavi mAMapNavi = AMapNavi.getInstance(this);

// Start point
NaviPoi start = new NaviPoi("Longcheng Garden", new LatLng(39.993308, 116.473199), "");
// Set the start angle
start.setDirection(35);

// End point
NaviPoi end = new NaviPoi("Peking University", new LatLng(39.917834, 116.397036), "");

// Calculate the route
mAMapNavi.calculateDriveRoute(start, end, null, PathPlanningStrategy.DRIVING_MULTIPLE_ROUTES_DEFAULT);

Calculate a Route with Waypoints

As of Navigation SDK V5.0.0, you can set up to 16 waypoints.

AMapNavi mAMapNavi = AMapNavi.getInstance(this);

// Start point
NaviPoi start = new NaviPoi("Longcheng Garden", null, "B000A8UF3J");

// End point
NaviPoi end = new NaviPoi("Peking University", null, "B000A816R6");

// Waypoints
List<NaviPoi> waysPoiIds = new ArrayList<NaviPoi>();
waysPoiIds.add(new NaviPoi("Waypoint 1", null, "B000A805M7"));
waysPoiIds.add(new NaviPoi("Waypoint 2", null, "B0FFFAADBU"));
waysPoiIds.add(new NaviPoi("Waypoint 3", null, "B0FFF5BER7"));

// Calculate the route
mAMapNavi.calculateDriveRoute(start, end, waysPoiIds, PathPlanningStrategy.DRIVING_MULTIPLE_ROUTES_DEFAULT);

Step 3: Handle the Result

On Success

When route calculation is successful, the AMapNaviListener.onCalculateRouteSuccess callback is triggered. In this callback, you can retrieve the route objects and display them on the map.

@Override
public void onCalculateRouteSuccess(AMapCalcRouteResult routeResult) {
    // Get the route data objects
    HashMap<Integer, AMapNaviPath> naviPaths = AMapNavi.getInstance(this).getNaviPaths();
    // Draw and display the routes
    // ...
}

You can also start navigation directly:

@Override
public void onCalculateRouteSuccess(AMapCalcRouteResult routeResult) {
    // Start navigation
    AMapNavi.getInstance(this).startNavi(NaviType.GPS);
}

On Failure

If route calculation fails, the AMapNaviListener.onCalculateRouteFailure callback is triggered. Implement your error handling logic in this callback.