Routes API

The Routes API provides 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. To request access, submit a business consultation through the official support ticket system.

Capabilities

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.

Before You Begin

Step 1

Apply for a 【Web Service API】 Key

Step 2

Enable overseas access for the applied Key by submitting a ticket to request the required 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	Apply for a Web Service API Key and submit a ticket for overseas permissions on the official website.	Yes	None
origin	Starting point	Format: longitude,latitude (comma-separated). Both values must not exceed 6 decimal places. Note: If either the origin or destination is an overseas coordinate, the API returns overseas route results.	Yes	None
destination	Destination	Format: longitude,latitude (comma-separated). Both values must not exceed 6 decimal places.	Yes	None
origin_id	Origin POI ID	When the origin is a Point of Interest (POI), providing this value improves route accuracy.	No	None
destination_id	Destination POI ID	When the destination is a Point of Interest (POI), providing this value improves route accuracy.	No	None
waypoints	Waypoints	Format: longitude,latitude (comma-separated). Multiple waypoints are separated by semicolons. Maximum of 16 waypoints. Waypoints are routed in the order specified.	No	None
strategy	Route planning strategy	32: Default recommendation 0: Speed priority (returns one route, may not be the shortest) 1: Cost priority (returns one route, avoids tolls, least time-consuming) 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	No	32
langCode	Response language	Default is zh. Options: zh, en.	No	None
sig	Digital signature	Methods for obtaining and using digital signatures.	No	None
callback	Callback function	A user-defined function name for JSONP callbacks.	No	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	0: Request failed; 1: Request succeeded
info			Status description	When status is 0, info returns the specific error reason. Otherwise, returns "OK". See the info status table for details.
count			Number of route solutions
route			Route planning information list
	origin		Origin coordinates	Format: lon,lat (comma-separated). Example: 117.500244,40.417801. Maximum 6 decimal places.
	destination		Destination coordinates	Format: lon,lat (comma-separated). Example: 117.500244,40.417801. Maximum 6 decimal places.
	taxi_cost		Taxi fare	Unit: Yuan. 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	Toll charges for this route	Unit: Yuan
		restriction	Traffic restriction result	0: Restriction avoided or no restriction on this route. 1: Restriction cannot be avoided; restricted sections exist on this route.
		traffic_lights	Number of traffic lights
		toll_distance	Toll road distance
		steps	Navigation segments
		step	Navigation segment	See the Navigation Step List below for details.

Navigation Step List

Name			Description	Specification
instruction			Driving instructions
orientation			Direction
road			Road name
distance			Distance of this road section	Unit: Meters
tolls			Toll charges for this section	Unit: Yuan
toll_distance			Distance of toll road section	Unit: Meters
toll_road			Main toll roads
polyline			Coordinate string for this road section	Format: x1,y1;x2,y2. Example: 116.481247,39.990704;116.481270,39.990726
action			Main navigation action	See the Driving Action List below for details.
assistant_action			Navigation assistance action	See the Driving Action List below for details.
tmcs			Driving navigation details	Contains TMC objects.
	distance		Length of this road	Unit: Meters
	status		Traffic condition of this road section	Unknown, clear, slow, congested, severely congested
	polyline		Trajectory of this road section	Format: 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 is only 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

The Compute Routes Matrix (M to N) API accepts an HTTPS request and returns either the ideal route between two locations, or distances and travel times for a matrix of routes between multiple origins and destinations.

Capabilities

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	Apply for a Web Service API Key and submit a ticket for overseas permissions on the official website.	Yes	None
origins	Starting points	Format: lng,lat (longitude first, comma-separated). Example: 117.500244,40.417801. Maximum 6 decimal places. Multiple coordinates are separated by semicolons. Supports up to 25 origins.	Yes	None (If more than 6 decimal places, truncate)
destinations	Destinations	Format: lng,lat (longitude first, comma-separated). Example: 117.500244,40.417801. Maximum 6 decimal places. Multiple coordinates are separated by semicolons. Supports up to 25 destinations.	Yes	None (If more than 6 decimal places, truncate)
travelMode	Transportation mode	Drive	No	Drive
routingPreference	Route planning strategy	1: Speed first	No	1
departureTime	Departure time (in seconds)	Optional. The departure time. If not set, defaults to the time of the request. Only future times are supported, with a maximum of 7 days. Unix timestamp.	No	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=1

Response Parameters Description

Name			Description	Specification
status			Return result status	0: Failure; 1: Success
info			Return status description	When status is 0, info returns the error reason. Otherwise, returns "OK".
infocode			Status code	10000 represents success. See the info status table for details.
routes			Computed routes
	route		Computed route
		originIndex	Origin index	1~25
		destinationIndex	Destination index	1~25
		status	Return status value	0: Success 1: Exceeds distance limit 2: Request timeout 111: Origin point matching failure 112: Via point matching failure 113: Destination point matching failure 141: Route calculation failure -1: Other
		distanceMeters	Distance	Distance in meters
		duration	Duration	Time in seconds