my.calculateRoute

Call this API to calculate the route.

Notes:

  • 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.

Notes:

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

  1. Get an API Key from Google: Follow Google's instructions to get an API key, which is required when using the Google Maps service.
  2. 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

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

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 status and errorMessage. Note that status corresponds to DirectionStatus in Google Maps. To learn more, refer to Status of Directions Query on Google Maps Platform.

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

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);
  }
});

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"
}