Routes API

Provide directions for transit, driving, or walking between multiple locations.

Because road networks, data, and algorithms can change over time, routing requests for the same start and end points may yield different results after a period of time.

Prompt

The Routes API for both domestic and overseas addresses shares the same endpoint. The overseas Web Services API is categorized as a premium service requiring prior authorization. For access requests, submit a business consultation through the official support ticket system.

Application

With the Routes API, you can:

Search for directions across multiple transportation modes, including transit, driving, and walking.
Generate multi-part directions using a series of waypoints.
Specify origins, destinations, and waypoints using latitude/longitude coordinates only.

The API calculates the most efficient routes, primarily optimizing for travel time. It also considers additional factors such as distance, number of turns, and other relevant criteria to determine the optimal route.

Guidelines

Step 1

Apply for a 【Web Service API】Key

Step 2

Enable overseas permissions for the applied Key by submitting a ticket to request overseas permissions

Step 3

Construct the HTTP request URL, including the Key obtained in Step 1 as a required parameter

Step 4

Receive and parse the data returned from the HTTP request (in JSON or XML format)

Unless otherwise specified, all input parameters and output data are encoded in UTF-8。

Compute Routes For Driving

Compute Routes For Driving API Service URL

URL	Request Method
https://sg-restapi.opnavi.com/v3/direction/driving?parameters	GET

The parameters represent both required and optional parameters. All parameters are separated by the ampersand character (&). The list below enumerates these parameters and their usage rules.

Request Parameters

Parameter Name	Description	Specification	Mandatory	Default
key	Service Authorization Token	Applying for a Web Service API Key and Submitting a Work Order for Overseas Permissions on Amap Map Official Website	Mandatory	None
origin	Starting Point	Please provide the starting point in the following format: longitude first, followed by latitude, separated by a comma. Ensure that both the longitude and latitude do not exceed 6 decimal places. Note‌: If either the starting point or destination is an overseas coordinate, the API will return overseas routes results.	Mandatory	None
destination	Destination	Please specify the destination in the following format: longitude first, followed by latitude, separated by a comma. Ensure that both the longitude and latitude do not exceed 6 decimal places.	Mandatory	None
origin_id	Start Point POI ID	When the starting point is a Point of Interest (POI), it is recommended to provide this value to enhance route accuracy.	Optional	None
destination_id	Destination POI ID	When the destination is a Point of Interest (POI), it is recommended to provide this value to enhance route accuracy.	Optional	None
waypoints	Waypoints	For waypoints, please use the following format: longitude and latitude are separated by a comma, with the longitude first and latitude second. Ensure that decimal places do not exceed 6 digits. Separate multiple coordinates with a semicolon. Maximum Limit‌: A maximum of 16 coordinates can be entered. If multiple waypoints are provided, they will be routed in the order specified by the user.	Optional	None
Strategy	Route Planning Strategy	32: Default Recommendation 0: Speed Priority (only one route returned), this route may not be the shortest 1: Cost Priority (only one route returned), avoids toll roads and is the least time-consuming route 33: Avoid congestion 34: Highway priority 35: Avoid highways 36: Less tolls 37: Main road priority 38: Fastest speed 39: Avoid congestion + Highway priority 40: Avoid congestion + Avoid highways 41: Avoid congestion + Less tolls 42: Less tolls + Avoid highways 43: Avoid congestion + Less tolls + Avoid highways 44: Avoid congestion + Main road priority 45: Avoid congestion + Fastest speed	Optional	32
langCode	Return result language	Default is zh, optional: zh, en;	Optional	None
sig	Digital Signature	Methods for Obtaining and Using Digital Signatures	Optional	None
callback	Callback Function	The callback value is a function name defined by the user.	Optional	None

Examples

https://sg-restapi.opnavi.com/v3/direction/driving?origin=103.988795,1.354462&destination=103.858456,1.302265&key=<your key>

Response Parameters Description

Name				Description	Specification
status				Result Status Value, Value is 0 or 1	0: Request failed; 1: Request succeeded
info				Return Status Description	When status is 0, specific error reasons will be returned in info. Otherwise, "OK" will be returned. For details, refer to theinfo status table.
count				Number of Driving Route Planning Solutions
route				Driving Route Planning Information List
	origin			Starting Coordinates	Rule: lon, lat (longitude, latitude), separated by ",", e.g., 117.500244, 40.417801, with no more than 6 decimal places for coordinates
	destination			Destination Coordinates	Rule: lon, lat (longitude, latitude), separated by ",", e.g., 117.500244, 40.417801, with no more than 6 decimal places for coordinates
	taxi_cost			Taxi Fare	Unit: Yuan, Note: Only returned when extensions=all
	paths			Driving Transfer Plan
		path		Driving Transfer Plan
		distance		Driving Distance	Unit: Meters
		duration		Estimated Travel Time	Unit: Seconds
		strategy		Navigation Strategy
		tolls		This navigation route has toll charges	Unit: Yuan
		restriction		Traffic Restriction Result	0 means the traffic restriction has been avoided or there is no restriction, i.e., there are no restricted sections on this route. 1 means the traffic restriction cannot be avoided, i.e., there are restricted sections on this route.
		traffic_lights		Number of Traffic Lights
		toll_distance		Toll Road Distance
		steps		Navigation Segment
			step	Navigation Segment	Details see Navigation Step List

Navigation Step List

Name			Description	Specification
instruction			Driving Instructions
orientation			Direction
road			Road Name
distance			Distance of this road section	Unit: Meter
tolls			This section is tolled	Unit: Yuan
toll_distance			Distance of toll road section	Unit: Meter
toll_road			Main toll roads
polyline			Coordinate string of this road section	Format as coordinate string, e.g., 116.481247,39.990704;116.481270,39.990726
action			Main navigation actions	See the driving action list for details
assistant_action			Navigation assistance actions	See the driving action list for details
tmcs			Driving navigation details	It contains TMC objects
	distance		The length of this road	Unit: meter
	status		Traffic condition of this road section	Unknown, clear, slow, congested, severely congested
	polyline		The trajectory of this road section	Specification: x1,y1;x2,y2
cities			Route Administrative Divisions
	name		Name
	citycode		Passing City Codes
	adcode		Passing Region Codes
	districts
		name	Passing County/District Names
		adcode	Passing district adcode

Driving action list

Note: The following information will only be returned when extensions=all

Main action list

No basic navigation actions

Turn left

Turn right

Drive to the front left

Drive to the front right

Drive to the rear left

Drive to the rear right

Make a U-turn to the left

Go straight

Keep left

Keep right

Enter the roundabout

Exit the roundabout

Decelerate

Assistance action list

Non-assisted navigation action

Entering the main road

Entering the service road

Entering the highway

Entering the ramp

Entering the tunnel

Enter the middle fork

Enter the right fork

Enter the left fork

Enter the right-turn lane

Enter the left-turn lane

Enter the middle lane

Enter the right lane

Enter the left lane

Keep right to enter the service road

Keep left to enter the service road

Keep right to enter the main road

Keep left to enter the main road

Keep right to enter the right-turn lane

Enter the ferry

Exit the ferry

Continue on the current road

Drive along the side road

Drive along the main road

Arrive at the exit

Arrive at the service area

Arrived at the toll booth

Arrived at the waypoint

Arrived at the destination

Turn left around the roundabout

Turn right around the roundabout

Go straight around the roundabout

Make a U-turn around the roundabout

Small roundabout, do not count exits

At the complex intersection, take the first exit on the right

At the complex intersection, take the second exit on the right

At the complex intersection, take the third exit on the right

At the complex intersection, take the fourth exit on the right

At the complex intersection, take the fifth exit on the right

At the complex intersection, take the first exit on the left

At the complex intersection, take the second exit on the left

At the complex intersection, take the third exit on the left

At the complex intersection, take the fourth exit on the left

At the complex intersection, take the fifth exit on the left

Enter the U-turn lane

Compute Routes For Walking

Compute Routes For Walking URL

URL	Request Method
https://sg-restapi.opnavi.com/v3/direction/walking?parameters	GET

The parameters represent both required and optional parameters. All parameters are separated by the ampersand character (&). The list below enumerates these parameters and their usage rules.

Request Parameters

Name	Meaning	Rule Description	Required	Default
key	Service access identifier	Your Web Service API key obtained from the Amap developer console.	Yes	None
origin	Starting point	Format: lon,lat (longitude, latitude), separated by a comma. Example: 117.500244,40.417801. Maximum 6 decimal places.	Yes	None
destination	Destination	Format: lon,lat (longitude, latitude), separated by a comma. Example: 117.500244,40.417801. Maximum 6 decimal places.	Yes	None
sig	Digital signature	Refer to the digital signature documentation for usage instructions.	No	None
output	Response data format	Supported values: JSON, XML.	No	JSON
callback	Callback function	User-defined function name. Only valid when output=JSON.	No	None

Example Request

https://sg-restapi.opnavi.com/v3/direction/walking?origin=135.781008,34.9966644&destination=135.772618,35.0059184&key=<YOUR_KEY>

Response Parameters

The response format is determined by the output parameter in the request.

Name			Meaning	Rule Description	Required	Default
status			Response status	0: failure; 1: success.	Yes	-
info			Status information	When status is 0, returns the error reason. Otherwise returns OK. See the info status table for details.	Yes	-
count			Total number of results	-	Yes	-
route			Route information list	Contains route details.	Yes	-
	origin		Origin coordinates	Starting point coordinates.	Yes	-
	destination		Destination coordinates	End point coordinates.	Yes	-
	paths		Walking route	Contains route details.	Yes	-
		distance	Walking distance	Unit: meters.	Yes	-
		duration	Estimated walking time	Unit: seconds.	Yes	-
		steps	Walking step list	Contains individual step details.	Yes	-
	step		Walking step	Each segment of the walking route.	Yes	-
		instruction	Step instruction	Navigation instruction for this step.	Yes	-
		road	Road name	Name of the road for this step.	Yes	-
		distance	Step distance	Unit: meters.	Yes	-
		orientation	Direction	Direction of travel for this step.	Yes	-
		duration	Estimated step duration	Unit: seconds.	Yes	-
		polyline	Step coordinates	Coordinate points for this step.	Yes	-
		action	Primary action	Main walking action. See the Walking Action List below.	Yes	-
		assistant_action	Assistant action	Supplementary walking action. See the Walking Action List below.	Yes	-
		walk_type	Walk type	Indicates special walkway types. See the Walk Type table below.	Yes	-

Walk Type Values

Value	Description
0	Normal road
1	Pedestrian crossing
3	Underpass
4	Footbridge
5	Subway passage
6	Park
7	Plaza
8	Escalator
9	Elevator
10	Cable car
11	Skybridge
12	Building passage
13	Pedestrian walkway
14	Ferry route
15	Sightseeing bus route
16	Slide
18	Widened road
19	Road connecting path
20	Stairs
21	Ramp
22	Bridge
23	Tunnel
30	Ferry

Walking Action List

Primary Actions	Secondary Actions
No basic navigation action	No secondary navigation action
Turn left	Turn left
Turn right	Turn right
Bear left	Bear left
Bear right	Bear right
Turn left back	Turn right back
Turn right back	Go straight
Go straight	Walk backward
Keep left	Walk forward
Keep right	Keep left
Cross the crosswalk	Keep right
Cross the overpass	Cross the crosswalk
Cross the underpass	Cross the overpass
Cross the plaza	Cross the underpass
Cross to the opposite side of the road	Cross the plaza
	Arrive at destination
	Enter the road on the right
	Enter the road on the left

Compute Routes For Motorcycle

The Motorcycle Route Planning service, powered by Amap's professional map data and motorcycle-specific traffic restrictions, provides optimized route calculations for motorcycles. Developers can retrieve motorcycle-appropriate route plans by specifying origin and destination coordinates. The service supports returning multiple routes in a single request, accepting multiple waypoints, and configuring different routing strategies for various business scenarios.

Compute Routes For Motorcycle URL

URL	Request Method
https://sg-restapi.opnavi.com/v5/direction/motor?parameters	GET

The parameters represent both required and optional parameters. All parameters are separated by the ampersand character (&). The list below enumerates these parameters and their usage rules.

Request Parameters

Name	Meaning	Rule Description	Required	Default
key	Amap API key	Web Service API key obtained from the Amap Open Platform.	Yes	-
origin	Origin coordinates	Longitude first, then latitude, separated by a comma. Maximum 6 decimal places.	Yes	-
destination	Destination coordinates	Longitude first, then latitude, separated by a comma. Maximum 6 decimal places.	Yes	-
origintype	Road type at the origin	Helps improve route accuracy at the start point. Values: 0 (normal road), 1 (overpass), 2 (underpass), 3 (main road), 4 (service road), 5 (tunnel), 7 (roundabout), 9 (parking lot interior).	No	-
strategy	Routing strategy	10 (default), 13 (prefer highway), 14 (avoid highway), 19 (minimize tolls).	No	10
alternative_route	Alternative routes	0 (disabled, returns one route), 1 (enabled, returns up to three routes).	No	0
waypoints	Waypoints	Ordered waypoint coordinates. Supports 1 waypoint by default. Multiple waypoints separated by semicolons (;). Maximum 16 waypoints.	No	-
avoidpolygons	Avoidance areas	Polygon areas to avoid. Supports 1 area by default, up to 16 vertices per area. Multiple areas separated by vertical bars (\|). Maximum 100 areas. If both avoidpolygons and avoidroad are provided, only avoidroad is applied. Avoidance areas must not exceed 81 km², otherwise they are ignored.	No	-
avoidroad	Avoidance road	Road name to avoid. Supports only one road. If both avoidpolygons and avoidroad are provided, only avoidroad is applied.	No	-
plate	License plate number	Used for traffic restriction evaluation. Example: 京AHA322.	No	-
show_fields	Response field filter	Controls which optional fields are included in the response. Rules: (1) See the show_fields field types in the response parameter table. (2) Multiple fields separated by commas. (3) If not set, only basic fields are returned. (4) Available values: cost (toll fees), tmcs (traffic conditions), navi (navigation actions), cities (city information), polyline (path coordinate string).	No	Empty
sig	Digital signature	Refer to the digital signature documentation for usage.	No	-
output	Response format	Supported value: JSON.	No	JSON
callback	Callback function	User-defined function name. Only valid when output is set to JSON.	No	-

Sample Request

https://sg-restapi.opnavi.com/v5/direction/motor?origin=135.781008,34.9966644&destination=135.772618,35.0059184&key=<YOUR_API_KEY>

Response Parameters

Name			Type	Description
status			string	API access status. 1 indicates success, 0 indicates failure.
info			string	Status description. Returns ok on success, or an error message on failure. See the error code table for details.
infocode			string	Status code. 10000 indicates success. See the info status table for details.
count			string	Total number of route plans returned.
route			object	Route plan list.
	origin		string	Origin coordinates.
	destination		string	Destination coordinates.
	paths		object	Route plan details.
		distance	string	Total route distance, in meters.
		restriction	string	Traffic restriction status. 0: restrictions avoided or not applicable (no restricted sections). 1: restrictions unavoidable (route contains restricted sections).
		steps	object	Route segments.
		instruction	string	Driving instruction for the segment.
		orientation	string	Direction of the road entered.
		road_name	string	Road name for the segment.
		step_distance	string	Distance of the segment, in meters.

Optional Fields (Require `show_fields` Parameter)

The following fields are only returned when explicitly requested via the show_fields parameter.

Name			Type	Description
show_fields			string	Controls which optional fields are included in the response.
	cost		object	Route time and cost details.
		duration	string	Total route duration, including segment-level durations.
		tolls	string	Total toll fees, in CNY. Includes segment-level tolls.
		toll_distance	string	Distance of toll road sections, in meters. Includes segment-level distances.
		toll_road	string	Primary toll road name.
		traffic_lights	string	Number of traffic lights on the route.
	tmcs		object	Segment-level traffic condition details.
		tmc_status	string	Traffic status. Possible values: unknown, smooth, slow, congested, severely congested.
		tmc_distance	string	Distance from the current coordinate point for which the traffic status applies, in meters.
		tmc_polyline	string	Coordinate string for the road section covered by this traffic status. Points separated by commas.
	navi		object	Detailed navigation action instructions.
		action	string	Primary navigation action.
		assistant_action	string	Secondary navigation action.
	cities		object	City information for route segments.
		adcode	string	Administrative area code.
		citycode	string	City code.
		city	string	City name.
		districts	object	District information.
		name	string	District name.
		adcode	string	District administrative code.
	polyline		string	Coordinate string for each route segment. Points separated by commas.

Compute Routes Matrix

Compute Routes Matrix（M to N），The Routes API is a service that accepts an HTTPS request and returns either the ideal route between two locations, or distances and travel times for a matrix of routes between different origin and destination locations.

Application

Routes from a location to a single or multiple destinations
A matrix of possible routes between many start and end locations.

Compute Routes Matrix API Service URL

URL	Request Method
https://sg-restapi.opnavi.com/v5/distance/matrix?parameters	POST

The parameters represent both required and optional parameters. All parameters are separated by the ampersand character (&). The list below enumerates these parameters and their usage rules.

Request Parameters

Parameter Name	Description	Specification	Mandatory	Default
key	Service Authorization Token	Applying for a Web Service API Key and Submitting a Work Order for Overseas Permissions on Amap Map Official Website	Mandatory	None
origins	Starting point	lng,lat（longitude first; "," separated; latitude last）e.g., 117.500244,40.417801 It is recommended that the latitude and longitude do not exceed 6 decimal places; format as x,y. Format as x,y ; x,y ; x,y..... Latitude and longitude are separated by ";"; supports up to 25 starting points	Mandatory	None (If there are more than 6 digits after the decimal point, truncate it)
destinations	Destination	lng,lat (longitude first; "," separated; latitude last) e.g., 117.500244,40.417801 It is recommended that the latitude and longitude do not exceed 6 decimal places; format as x,y ; x,y ; x,y..... Latitude and longitude are separated by ";"; supports up to 25 destinations	Mandatory	None (If there are more than 6 digits after the decimal point, truncate it)
travelMode	Transportation mode	Drive	Optional	Drive
routingPreference	Route planning strategy	1:Speed First	Optional	1
departureTime	Departure time (in seconds)	Optional. The departure time. If you don't set this value, then this value defaults to the time that you made the request Only future times are supported, with a maximum of 7 days Unix timestamp	Optional	None

Examples

https://sg-restapi.opnavi.com/v5/distance/matrix?key=<your key>&origins=126.983319,35.806658&destinations=126.983319,35.806658;127.000000,36.000000;127.100000,36.100000;127.200000,36.200000;127.300000,36.300000;127.400000,36.400000;127.500000,36.500000;127.600000,36.600000;127.700000,36.700000;127.800000,36.800000&routingPreference=TRAFFIC_AWARE

Response Parameters Description

Name			Description	Specification
status			Return Result Status Value	The value is 0 or 1, 0 means failure; 1 means success
info			Return Status Description	Return status description, when status is 0, info returns the reason for the error, otherwise returns "OK".
infocode			Status Code	Return status description, 10000 represents correct, refer to info status table for details
routes			Compute Routes
	route		Compute Routes
		originIndex	Origin Index	1~25
		destinationIndex	Destination Index	1~25
		status	Return Status Value	0: Success 1: Exceeds distance limit 2: Request timeout 111: Start point matching failure 112: Via point matching failure 113: Destination point matching failure 141: Route calculation failure -1: Other
		distanceMeters	Distance	Distance (meters)
		duration	Duration	Time taken (seconds)