my.calculateRoute

2026-10-12 01:00

Call this API to calculate the route.

Supported types of mini programs: DSL, H5+

Note:
For mini programs released to Alipay CN, the map-related APIs are backed by Gaode Map.
For mini programs released to other Alipay+ partner apps, the map-related APIs are backed by Google Maps. These API calls are charged so you need to provide your own gAPIKey instead of using the super app's API key. Contact our technical support for details.
The IDE simulator cannot obtain the return values. Use the real development environment to obtain the return values.

Parameters

Property	Type	Required	Description
searchType	String	No	Indicates the mode of transportation. Valid values are: `walk`: walking `bus`: public transit `drive`: driving `ride`: cycling Note: The default value is `walk`.
startLat	Number	Yes	Indicates the latitude of the starting point.
startLng	Number	Yes	Indicates the longitude of the starting point.
endLat	Number	Yes	Indicates the latitude of the endpoint.
endLng	Number	Yes	Indicates the longitude of the endpoint.
throughPoints	Array	No	For Google Maps: Indicates a set of points along the route. This parameter is not available when the value of searchType is `bus`, that is, this parameter is available when the value of searchType is `walk`, `drive`, or `ride`. For Alipay CN (Gaode Map): Indicates a set of points along the route. This parameter is only available for driving, that is, when the value of searchType is `drive`.
mode	Number	No	Indicates different modes of the route. It is only supported for the driving and public transit modes, that is, when the value of searchType is `drive` or `bus`. For more information, see Mode values. Note: This parameter is only available for Alipay CN (Gaode Map).
city	String	Yes	Indicates the city of the route. It is required in the public transit mode, that is, when the value of searchType is `bus`. Note: This parameter is only available for Alipay CN (Gaode Map).
destinationCity	String	Yes	Indicates the destination city where the route ends. This parameter is required in the cross-city public transit mode, that is, when the value of searchType is `bus`. Note: This parameter is only available for Alipay CN (Gaode Map).
gAPIKey	String	No	Indicates the API key required to call this API. To learn how to get gAPIKey, refer to API key. Note: This parameter is only available for Google Maps. By default, the super app's API key is used. If you do not provide this parameter and your mini program is prevented from using the super app's API key, an error will occur when calling this API.

Mode values

The following table lists the detailed mode values, only available for Alipay CN (Gaode Map):

Mode	Bus	Drive
0	Fastest route	Speed first (time)
1	Most economical route	Least cost (The fastest toll-free route)
2	Minimum transfers	Shortest distance
3	Shortest walking distance	Avoid expressways
4	Coziest route	Real-time route planning (to avoid traffic jams)
5	Avoid subway	Multiple strategies (comprehensively considering the speed first, least cost, and shortest distance strategies)
6	-	Avoid highways
7	-	Avoid highway and toll roads
8	-	Avoid toll roads and traffic jams
9	-	Avoid highways, toll roads, and traffic jams

API key

You can use your own API key when calling the map-related APIs backed by Google Maps. Follow the steps below for configuration:

Get an API Key from Google: Follow Google's instructions to get an API key, which is required when using the Google Maps service.
Encrypt your Google API key: To encrypt your Google API key, contact our technical support. Then replace ENCRYPTED_CUSTOM_GOOGLE_API_KEY with your encrypted Google API key:

copy
this.mapCtx.showRoute({   
  data: "",
  gAPIKey: "ENCRYPTED_CUSTOM_GOOGLE_API_KEY", // The API key must be encrypted
  success: function (res) {   },
  fail: function (res) {  }
});

Error codes

Google Maps

Error code

Error message

Further action

1900

The default error code is 1900 (compatible with Gaode Map, which means the 1900 error code of Gaode Map is used to throw any error instance of Google Maps).

For error details about Google Maps, see the status and errorMessage in the folloiwng sample code.

Note: the status corresponds to DirectionStatus in Google Maps. To learn more, refer to Status of Directions Query on Google Maps Platform.

Invalid parameters

Please check wehther the map key is configured correctly.

copy
{
    "success": false,
    "errorCode": 1900,
    "status": "INVALID_REQUEST",
    "errorMessage": "Exactly two waypoints required in transit requests"
}

Gaode Map

copy
{
    "success": false,
    "errorCode": 1900
}

The following provides the error codes and descriptions of Gaode Map in different mobile operating systems:

Success callback function

The incoming parameter is an object parameter with the following attributes:

Property	Type	Description
success	Boolean	Specifies whether the API call is successful. When the value is `true`, the API call is successful.
distance	Number	Indicates the distance between the starting point and the endpoint.
duration	Number	Indicates the length of time spent according to the planned route, in seconds.

Sample code

DSL

copy
//.js
my.calculateRoute({
  searchType: "walk",        // searchType: "walk", "bus", "drive", "ride". Default value: walk. Added in v10.1.50.
  startLat: 1.339712,        // The latitude of the starting point.
  startLng: 103.855457,      // The longitude of the starting point.
  endLat: 1.342983,          //  The latitude of the end point.
  endLng: 103.867935,        // The longitude of the end point.
  throughPoints: [{ lat: 1.343573, lng: 103.861916 }], // A set of points along the route.
  mode:0,                          // Only available for Alipay CN 
  city:'hangzhou',                 // Only available for Alipay CN
  destinationCity:'hangzhou',      // Only available for Alipay CN
  success:(res)=>{
    console.log(res.distance);
    console.log(res.duration);
  }
});

H5+

copy
AlipayJSBridge.call('calculateRoute', {
  searchType: "walk",        // searchType: "walk", "bus", "drive", "ride". Default value: walk. Added in v10.1.50.
  startLat: 1.339712,        // The latitude of the starting point.
  startLng: 103.855457,      // The longitude of the starting point.
  endLat: 1.342983,          //  The latitude of the end point.
  endLng: 103.867935,        // The longitude of the end point.
  throughPoints: [{ lat: 1.343573, lng: 103.861916 }], // A set of points along the route.
  mode: 0,                          // Only available for Alipay CN 
  city: 'hangzhou',                 // Only available for Alipay CN
  destinationCity: 'hangzhou',      // Only available for Alipay CN
}, function (res) {
  alert('AlipayJSBridge calculateRoute result:\n' + JSON.stringify(res));
});

Sample of the success callback function

copy
{
    "distance": 328,
    "duration": 262,
    "success": true
}

Sample of the fail callback function

copy
{
    "success": false,
    "errorCode": 1900,
    "status": "INVALID_REQUEST",
    "errorMessage": "Exactly two waypoints required in transit requests"
}