Calculate a Route

Bing
 

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.

See Calculate a Truck Route documentation for information on making truck based routing requests.

To overlay a route on a static map by using the Imagery API, see Get a Static Map.

System_CAPS_ICON_note.jpg 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  

Template Parameters

System_CAPS_ICON_note.jpg Note

See the Common Parameters and Types section for additional common parameters to use with these URLs.

Common parameters include:

  • Output Parameters: Includes response output types and the JSON callback parameters.
  • Culture Parameter: Includes a list of the supported cultures.
  • User Context Parameters: Includes parameters that set user location and viewport values to help determine locations. For example, these values may help prioritize a set of possible locations when you specify a partial address for a waypoint.

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.

ParameterAliasDescriptionValues
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
avoidOptional. 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.

- highways: Avoids the use of highways in the route.
- tolls: Avoids the use of toll roads in the route.
- minimizeHighways: Minimizes (tries to avoid) the use of highways in the route.
- minimizeTolls: Minimizes (tries to avoid) the use of toll roads in the route.
- ferry: Avoids the use of ferries in the route.

   Note: If you specify more than one option for a road type, then the most restrictive option is used. For example, if you set the avoid parameter to both highways and minimizeHighways, the highways option is used and all highways are avoided.

 Examples:

avoid=highways

avoid=highways,tolls
distanceBeforeFirstTurndbftOptional. 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
headinghdOptional. 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
optimizeoptmzOptional. Specifies what parameters to use to optimize the route.One of the following values:

- distance: The route is calculated to minimize the distance. Traffic information is not used.
- time [default]: The route is calculated to minimize the time. Traffic information is not used.
- timeWithTraffic: The route is calculated to minimize the time and uses current traffic information.
- timeAvoidClosure: The route is calculated to minimize the time and avoid road closures. Traffic information is not used in the calculation.

 Example: optimize=time
routeAttributesraOptional. Specify to include or exclude parts of the routes response.One or more of the following values:

- excludeItinerary: Do not include detailed directions in the response. Detailed directions are provided as itinerary items and contain details such as written instructions and traffic location codes.
- routePath: Include a set of point (latitude and longitude) values that describe the route’s path in the response.
- transitStops: Include information about transit stops for transit routes.
- routeSummariesOnly: Include only travel time and distance for the route, and do not provide other information. Only supported for 2 waypoint routes.
- regionTravelSummary: Include travel summary of distance and time by two entity types: country (e.g. US, Canada) and administrative division or subregion (e.g. "state" in US and "province" in Canada). This value can be specified along with all the other routeAttributes values above.
- all: Used to specify the following attributes as a group: excluteItinerary, routePath, and transitStops.

 Note: When you set the routeAttributes parameter, the routePathOutput parameter is ignored.

 Example: ra=routePath,transitStops
routePathOutputrpoOptional. 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:

- Points: A list of Point values for the route’s path is provided in the response.
- None [default]: No information about the route’s path is provided in the response.

 Example: routePathOutput=Points

 Note: The current recommended way to get route points is to use routeAttributes parameter.

- The parameter setting routeAttributes=routePath returns the same values as routePathOutput=Points.
- If the routeAttributes parameter is included in the request with any value (not only routePath), the routePathOutput parameter is ignored.
tolerancestlOptional. 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.

 A visual example of how tolerances work

 Example: tl=0.00000344978
distanceUnitduOptional. The units to use for distance in the response.One of the following values:

- Mile or mi
- Kilometer or km [default]

 Example: distanceUnit=mi
dateTimedtRequired 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:

- dateTime=03/01/2011 05:42:00
- dateTime=05:42:00 [assumes the current day]
- dateTime=03/01/2011 [assumes the current time]
timeTypettRequired 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:

- Arrival: The dateTime parameter contains the desired arrival time for a transit request.
- Departure: The dateTime parameter contains the desired departure time for a transit request.
- LastAvailable: The dateTime parameter contains the latest departure time available for a transit request.
maxSolutionsmaxSolnsOptional. 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 Note: This parameter is available for the Driving and Transit travel modes for routes between two waypoints. This parameter does not support routes with more than two waypoints. For driving routes, you must not set the avoid and distanceBeforeFirstTurn parameters. The maxSolutions parameter is supported for routes in the United States, Canada, Mexico, United Kingdom, Australia, and India.
travelModeOptional. The mode of travel for the route.One of the following values:

- Driving [default]
- Walking
- Transit
optimizeWaypointsoptWpOptional, available only if the travel mode is Driving. If true, the Route API reorders the specified waypoints so that the route is optimized for the value specified by the optimize parameter. The ordering of the first and last waypoints (wp.0 and wp.n) is never changed.

Note: The specified route must contain more than two waypoints.
Either true or false

Default: false

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  

Find an optimized route with multiple waypoints.

This example returns an optimized route for a list of waypoints in Seattle, Washington. The route is optimized for time, incorporating traffic information. At least three waypoints are required and waypoint optimization is only available for driving directions. For a detailed example, see Find an Optimized Route with Multiple Waypoints.

http://dev.virtualearth.net/REST/V1/Routes/Driving?wp.0=86+Pike+Pl%2C+Seattle%2C+WA+98101&wp.1=Troll+Ave+N%2C+Seattle%2C+WA+98103&wp.2=3800+Montlake+Blvd+NE%2C+Seattle%2C+WA+98195&wp.3=1000+4th+Ave%2C+Seattle%2C+WA+98104&wp.4=5400+Ballard+Ave+NW%2C+Seattle%2C+WA+98107&optwp=true&optimize=timeWithTraffic&key=BingMapsKey

System_CAPS_ICON_note.jpg 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

Driving Route Example
Walking Route Example
Transit Route Example
Driving Route with Route Path Example
Driving Route using Tolerances Example

Show: