Calculate a Route
Use the following URL templates to get a walking, driving or transit route by specifying a series of waypoints. A waypoint is a specified geographical location defined by longitude and latitude that is used for navigational purposes. The route includes information such as route instructions, travel duration, travel distance or transit information. You can also request a set of route points.
To overlay a route on a static map by using the Imagery API, see Get a Static Map.
 Note |
|---|
These templates support both HTTP and HTTPS protocols. |
You can specify up to 25 waypoints for a route. Each set of waypoints creates a separate route leg. Between any two (2) waypoints, you can have up to 10 intermediate viaWayPoints. ViaWaypoints define the route path and do not create route legs.
Find a driving route.
http://dev.virtualearth.net/REST/v1/Routes? wayPoint.1=wayPoint1&viaWaypoint.2=viaWaypoint2&waypoint.3=wayPoint3&wayPoint.n=wayPointn&heading=heading&optimize=optimize&avoid=avoidOptions&distanceBeforeFirstTurn=distanceBeforeFirstTurn&routeAttributes=routeAttributes&maxSolutions=maxSolutions&tolerances=tolerance1,tolerance2,tolerancen&distanceUnit=distanceUnit&mfa=mfa&key=BingMapsKey
Find a walking, driving or transit route by specifying the mode of travel.
For a list of transit agencies, see Bing Maps Transit Coverage. You can request up to three (3) driving or transit route options between two waypoints by using the maxSolutions parameter.
http://dev.virtualearth.net/REST/v1/Routes/travelMode?wayPoint.1=wayPoint1&viaWaypoint.2=viaWaypoint2&waypoint.3=wayPoint3&wayPoint.n=wayPointn&heading=heading&optimize=optimize&avoid=avoidOptions&distanceBeforeFirstTurn=distanceBeforeFirstTurn&routeAttributes=routeAttributes&timeType=timeType&dateTime=dateTime&maxSolutions=maxSolutions&tolerances=tolerance1,tolerance2,tolerancen&distanceUnit=distanceUnit&mfa=mfa&key=BingMapsKey
| Note |
|---|
See the Common Parameters and Types section for additional common parameters to use with these URLs. Common parameters include:
When an alias is provided, you can use the alias to shorten the length of the query parameter. For example, waypoint.1=47.610,-122.107 can be shortened to wp.1=47.610,-122.107. Parameter values are not case-sensitive. |
Parameter | Alias | Description | Values | ||
|---|---|---|---|---|---|
waypoint.n viaWaypoint.n | wp.n vwp.n | waypoint.n: Required. Specifies two or more locations that define the route and that are in sequential order. viaWaypoint.n: Optional Specifies one or more locations that define intermediate points of a route between waypoints. | A route is defined by a set of waypoints and viaWaypoints (intermediate locations that the route must pass through). The index (n value) for the set of waypoints and viaWaypoints is an integer starting with 0 or 1. The waypoint and viaWaypoint index values must be sequential and must always increment by 1. Both waypoint and viaWaypoint locations can be specified as a Point, a landmark, or an address. For more information about Point values, see Location and Area Types. You can have a maximum of 25 waypoints, and a maximum of 10 viaWaypoints between each set of waypoints. The start and end points of the route cannot be viaWaypoints. For transit routes and when more than one route is requested (maxSolutions > 1), you must specify only two waypoints, and viaWaypoints are not supported.
Examples: waypoint.1=47.610,-122.107 [Point] wp.1=Seattle,WA [landmark] waypoint.1=1%20Microsoft%20Way%20Redmond%20WA%20 [address] &waypoint.1=Seattle&viaWaypoint.2=Kirkland&waypoint.3=Redmond [viaWaypoint] Incorrect set of waypoints. The following set of values is not valid because there is no waypoint.2. &waypoint.1=San%20Francisco&waypoint.3=Seattle The following set of values is not valid because a viaWaypoint is specified as the starting waypoint. &viaWaypoint.1=1%20Microsoft%20Way%20Redmond%20WA&waypoint.2=Bellevue&waypoint.3=Seattle | ||
avoid | Optional.Specifies the road types to minimize or avoid when a route is created for the driving travel mode. | A comma-separated list of values from the following list that limit the use of highways and toll roads in the route. In the definitions below, “highway” also refers to a “limited-access highway”. If no values are specified, highways and tolls are allowed in the route.
Examples: avoid=highways avoid=highways,tolls | |||
distanceBeforeFirstTurn | dbft | Optional. Specifies the distance before the first turn is allowed in the route. This option only applies to the driving travel mode. | An integer distance specified in meters. Use this parameter to make sure that the moving vehicle has enough distance to make the first turn. Examples: distanceBeforeFirstTurn=500 dbft=500 | ||
heading | hd | Optional. Specifies the initial heading for the route. | An integer value between 0 and 359 that represents degrees from north where north is 0 degrees and the heading is specified clockwise from north. For example, setting the heading of 270 degrees creates a route that initially heads west. Example: heading=90 | ||
optimize | optmz | Optional. Specifies what parameters to use to optimize the route. | One of the following values:
Example: optimize=time | ||
routeAttributes | ra | Optional. Specify to include or exclude parts of the routes response. | One or more of the following values:
Note: When you set the routeAttributes parameter, the routePathOutput parameter is ignored. Example: ra=routePath,transitStops | ||
routePathOutput | rpo | Optional. Specifies whether the response should include information about Point (latitude and longitude) values for the route’s path. | Note: This is a legacy parameter. The current recommended way to get route points is to use the routeAttributes parameter. One of the following values:
Example: routePathOutput=Points Note: The current recommended way to get route points is to use routeAttributes parameter.
| ||
tolerances | tl | Optional. Specifies a series of tolerance values. Each value produces a subset of points that approximates the route that is described by the full set of points. This parameter is only valid when the routePathOutput parameter is set to Points. | A set of comma-separated double values. Each value specifies a tolerance that is used to reduce the number of points needed to display a route on a map and still maintain the route shape. If a point is removed and the new route still falls within the specified tolerance of the old route, then the point is not included in the subset of points returned for that tolerance. You may find it useful to define tolerances for different zoom levels, screen resolutions or other display parameters. You can specify a maximum of seven (7) tolerance values. The tolerance is specified in degrees. A degree of latitude is approximately 60 nautical miles, 111 kilometers or 69 statute miles. Therefore, a tolerance value of 0.00001 represents a distance of about one (1) meter in the north-south direction. The distance represented by a degree of longitude varies with latitude. For example at 45 degrees of longitude, a degree of latitude is 111.132 km and a degree of longitude is 78.847 km. At the equator, these values are almost equal with latitude at 100.754 km and longitude at 111.320 km. As you approach the poles, the distance associated with a degree of latitude decreases, and fewer points will be excluded for the same tolerance value. For more information about how longitude distances change with latitude, see Longitude (Wikipedia). The following diagram illustrates how a tolerance value is used.  Example: tl=0.00000344978 | ||
distanceUnit | du | Optional. The units to use for distance in the response. | One of the following values:
Example: distanceUnit=mi | ||
dateTime | dt | Required when the travel mode is Transit. The dateTime parameter identifies the desired transit time, such as arrival time or departure time. The transit time type is specified by the timeType parameter. Optional for Driving. When specified and the route is optimized for timeWithTraffic, predictive traffic data is used to calculate the best route for the specified date time. | A string that contains the date and time formatted as a DateTime value. For information about the string representation options for DateTime values, see DateTime.Parse Method (String). Examples:
| ||
timeType | tt | Required when the travel mode is Transit Specifies how to interpret the date and transit time value that is specified by the dateTime parameter. | One of the following values:
| ||
maxSolutions | maxSolns | Optional. Specifies the maximum number of transit or driving routes to return. | A string that contains an integer value between 1 and 3. The default value is 1. Example: maxSolns=3
| ||
travelMode | Optional. The mode of travel for the route. | One of the following values:
|
A Route resource is returned when you make a request with one of the following URLs. For more information about the Route resource, see Route Data. For more information about the common response syntax for the Bing Maps REST Services, see Common Response Description. JSON and XML responses are provided for the URL examples in the following section.
These URLs support JSON (application/json) and XML (application/xml) response formats. A JSON response is provided by default, unless you request XML output by setting the output (o) parameter. For more information, see Output Parameters.
Find a driving route.
The following example shows how to request a driving route between two locations that minimizes the use of toll roads. To view the complete XML and JSON responses, see Driving Route Example.
http://dev.virtualearth.net/REST/V1/Routes/Driving?o=xml&wp.0=london&wp.1=leeds&avoid=minimizeTolls&key=BingMapsKey
Find a driving route that includes an intermediate route point (viaWaypoint).
The following example shows how to request a driving route between two locations that includes an intermediate viaWaypoint. ViaWaypoints are used to direct a route through specific locations and do not create a new route leg like waypoints.
http://dev.virtualearth.net/REST/V1/Routes/Driving?o=xml&wp.0=Seattle,WA&vwp.1=Portland,OR&wp.2=Bend,OR&avoid=minimizeTolls&key=BingMapsKey
Find a walking route that minimizes distance.
This example returns a walking route from the Eiffel Tower to the Louvre Museum in Paris, France. The route is optimized for distance and returns the results in XML. To view the complete XML and JSON responses, see Walking Route Example.
http://dev.virtualearth.net/REST/V1/Routes/Walking?wp.0=Eiffel%20Tower&wp.1=louvre%20museum&optmz=distance&output=xml&key=BingMapsKey
Find a transit route.
The following example shows how to request a transit route between the Golden Gate Bridge and Fisherman’s Wharf in San Francisco for 3 PM on the current day. To view the complete XML and JSON responses, see Transit Route Example.
%http://dev.virtualearth.net/REST/V1/Routes/Transit?wp.0=Golden%20Gate%20Bridge&wp.1=Fishermans%20Wharf&timeType=Departure&dateTime=3:00:00PM&output=xml&key=BingMapsKey
Find up to three driving route options between New York, NY and Philadelphia, PA.
The following example requests up to three (3) driving route options between New York, New York and Philadelphia, Pennsylvania.
http://dev.virtualearth.net/REST/V1/Routes?wp.0=New%20York,NY&wp.1=Philadelphia,PA&maxSolns=3&key=BingMapsKey
Find up to three driving route options between New York, NY and Philadelphia, PA.
The following example requests up to three (3) driving route options between New York, New York and Philadelphia, Pennsylvania and exclude detailed instructions for alternate routes.
http://dev.virtualearth.net/REST/V1/Routes?wp.0=New%20York,NY&wp.1=Philadelphia,PA&maxSolns=3&mfa=1&key=BingMapsKey
Two ways to specify waypoints for a driving route: Point (latitude and longitude coordinates) and location names.
The following two examples show how to request a route between San Francisco and San Diego by using latitude and longitude coordinates and by using location names.
http://dev.virtualearth.net/REST/V1/Routes?wp.0=37.779160067439079,-122.42004945874214&wp.1=32.715685218572617,-117.16172486543655&key=BingMapsKey
http://dev.virtualearth.net/REST/V1/Routes?wp.0=San%20Francisco&wp.1=San%20Diego&key=BingMapsKey
Find a driving route between Redmond, Washington and Seattle, Washington that specifies an initial heading of 90 degrees (east) and that requests the results uses miles as the distance unit.
http://dev.virtualearth.net/REST/v1/Routes/Driving?waypoint.0=redmond&heading=90&waypoint.1=seattle&du=mi&key=BingMapsKey
Find a walking route between two addresses.
This example shows how to request a walking route between two addresses.
http://dev.virtualearth.net/REST/V1/Routes/Walking?wp.0=11025%20NE%208th%20St%20Bellevue%20WA&wp.1=700%20Bellevue%20Way%20NE%20Bellevue WA&key=BingMapsKey
Find a driving route that minimizes the distance and specifies that the first turn must be at least 500 meters from the starting point.
The following example optimizes a route between two locations for distance. The first turn on the route must be 500 meters or more from the starting point.
http://dev.virtualearth.net/REST/V1/Routes?wp.0=11025%20NE%208th%20St%20Bellevue&wp.1=1%20Microsoft%20Way%20Redmond%20WA&optmz=distance&dblt=500&key=BingMapsKey
Find a driving route that minimizes travel time based on current traffic conditions.
The following example optimizes a route between two locations and takes the current traffic conditions into account.
http://dev.virtualearth.net/REST/V1/Routes?wp.0=Bellevue,WA&wp.1=Bothell,WA&optmz=timeWithTraffic&key=BingMapsKey
Find a driving route that does not use highways or toll roads.
The following example returns a driving route between the cities of Buffalo and Syracuse in New York State. The avoid parameter specifies to not use toll roads or highways. Therefore, the returned route does not use the interstate highway I-90 which would otherwise be part of the route.
http://dev.virtualearth.net/REST/V1/Routes/Driving?wp.0=Buffalo&wp.1=Syracuse&avoid=tolls,highways&key=BingMapsKey
Find a driving route and request a set of points that define the route.
This example returns a driving route from the Minneapolis, Minnesota to St. Paul, Minnesota. The route is optimized for distance and requests point values for the route’s path. The results are returned in JSON. To view the complete XML and JSON responses, see Driving Route with Route Path Example.
http://dev.virtualearth.net/REST/V1/Routes/Driving?wp.0=Minneapolis,MN&wp.1=St%20Paul,MN&optmz=distance&routeAttributes=routePath&key=BingMapsKey
Find a driving route and exclude the detailed directions (itinerary items).
This example returns a driving route from the Minneapolis, Minnesota to St. Paul, Minnesota, and excludes the detailed itinerary items from the response.
http://dev.virtualearth.net/REST/V1/Routes/Driving?wp.0=Minneapolis,MN&wp.1=St%20Paul,MN&routeAttributes=excludeItinerary&key=BingMapsKey
Find a driving route and request a route path and a subset of route path points based on tolerance values.
This example returns a driving route from the Minneapolis, Minnesota to St. Paul, Minnesota. The route is optimized for distance and requests point values for the route’s path. In addition to the full set of route points, a list of tolerances is specified. For each tolerance value, a subset of points is returned in the response. The route defined by each subset of points approximates the route defined by all the points. The difference allowed between the two routes is defined by the tolerance value. To view examples of these subsets of points in the response, see Driving Route using Tolerances Example.
http://dev.virtualearth.net/REST/V1/Routes/Driving?o=xml&wp.0=44.979035,-93.26493&wp.1=44.943828508257866,-93.09332862496376&optmz=distance&routeAttributes=routePath&tl=0.00000344978,0.0000218840,0.000220577,0.00188803,0.0169860,0.0950130,0.846703&key=BingMapsKey
| Note |
|---|
For more details about these HTTP status codes, see Status Codes and Error Handling. |
When the request is successful, the following HTTP status code is returned.
200
When the request is not successful, the response returns one of the following errors.
400
401
404
500
503