MapContext.showRoute

2023-04-28 21:00

Get the default walking route planned. Only one route is displayed.

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`.
routeColor	HexColor	No	Indicates the color of the route. This parameter takes effect only in 2D maps.
iconPath	String	No	Indicates the texture of the route. In base library v1.11.0 and earlier versions, this parameter takes precedence over routeColor in 3D maps. Routes are covered by texture instead of a solid color. It's suggested that this parameter is not specified in base library v1.13.0 and later versions, because a default texture pattern is provided in 3D maps. It's also suggested to set the size of the image to an integer power of 2, such as 64*64.
iconWidth	Int	No	Indicates the width of the texture. This parameter takes effect only in base library v1.11.0 and earlier versions. It's suggested that this parameter is not specified in base library v1.13.0 and later versions, because a default texture width is set in 3D maps.
routeWidth	Int	No	Indicates the width of the route. This parameter takes effect only when texture is not used. It's suggested that this parameter is not specified in base library v1.13.0 and later versions, because a default value is set in 2D maps and it is no longer required in 3D maps.ww
zIndex	Int	No	The Z-axis index of the overlay.
mode	Int	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 (Choose 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

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
onReady() {
  // Call my.createMapContext to obtain the map context.
  this.mapCtx.showRoute({
      searchType: "walk",         // searchType: "walk", "bus", "drive", "ride". Default value: walk. Added in v10.1.50.
      startLat: 1.339712,        // The latitude of the start point.
      startLng: 103.855457,       // The longitude of the start 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. It is only available for driving planning, that is, available when searchType="drive". Added in v10.1.50.
      routeColor: '#FFB90F',       // The color of the route. This parameter takes effect only in 2D maps in versions later than 10.1.50.
      iconWidth: 10,           // The width of the texture. In v10.1.35, this parameter takes effect only when iconPath is specified. We recommend that you do not specify this parameter in v10.1.50. A default texture width is set in 3D maps.
      routeWidth: 10,          // The width of the route. This parameter takes effect when texture is not used. We recommend that you do not specify this parameter in v10.1.50, because a default value is set in 2D maps and it is no longer required in 3D maps.
      zIndex: 4,             // The z-axis index of the overlay 10.1.35
      mode: 0,             // Only supported in driving and public transit modes. For more information about its values, see the mode values list below.
      city: 'Singapore',         // Required in public transit mode.
      destinationCity: 'Singapore',    // Required in cross-city public transit mode.
      success:(res)=>{
      console.log(res.distance);
      console.log(res.duration);
    }
  });
},
onLoad() {
  //  this.mapCtx = my.createMapContext('map');
  this.mapCtx = my.createMapContext('map');
  this.setData({
    includePoints:[ {
      latitude: 1.347016,
      longitude: 103.860167,
    },{
      latitude: 1.351628,
      longitude: 103.863718,
    }]
  })
}

copy
//.axml
<map
     id="map"
     customMapStyle="light"
     longitude="{{longitude}}"
     latitude="{{latitude}}"
     scale="{{scale}}"
     controls="{{controls}}"
     onControlTap="controltap"
     markers="{{markers}}"
     onMarkerTap="markertap"
     polyline="{{polyline}}"
     polygon="{{polygon}}"
     circles="{{circles}}"
     onRegionChange="regionchange"
     onTap="tap"
     onCalloutTap="callouttap"
     show-location style="width: 100%; height: 200px;"
     include-points="{{includePoints}}"
     ground-overlays="{{ground-overlays}}">

Sample of the success callback function

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