Open Directions Service Developer's Guide

The Route Service provides a simple interface to get routing, narrative, and shapes. Release notes are available here. Comments, feedback, and support questions can be posted in our Open Forums.

Hello, World!

In its most basic form, the Route Service lets you request directions between two or more points. The service can return results in JSON or XML, either of which can easily be parsed by client applications.

The following example demonstrates a simple request to get driving directions from Lancaster, PA to York, PA. The JavaScript code which sends the request and displays the result can be viewed here.

(Route will be displayed below)    


Contents


Overview

  1. Route - The core routing function. Provides information on how to get from one location to one (or more) other locations.
  2. OptimizedRoute- A function that allows a user to find the route with the most optimized drive time / shortest distance / walking time that includes all intermediate locations. The origin and destination locations remain fixed, but the intermediate locations are re-ordered to find the optimal path through the set of locations.
  3. RouteMatrix- A function that allows a user to find the times and distances between a set of points.
  4. RouteShape - A helper function which returns only the geometry associated with a previous Route call.
  5. PathFromRoute - A helper function which the distances from a route to the points given.
  6. AlternateRoutes - A helper function which returns alternative routes to the first one given.

The input to this function is a Route Request, which is described via Key/Value pair request parameters, or as JSON or XML text.

The Route Service is designed to accept and return a variety of formats. All requests are submitted and returned via HTTP. The input format supplied to the Route Service is not required to be the same format returned from the Route Service.

The route service does allow for multipoint routes, up to 50 locations and under 8000 miles (See the Specifying Lat/Lng Locations section below for details).

Supported input formats:

  • Key/Value pairs - All route parameters are supplied via request parameters.
  • JSON - The route parameters are supplied via JSON-formated text, either in the body of an HTTP POST request or as the "json" parameter of an HTTP GET request.
  • XML - The route parameters are supplied via XML-formatted text, either in the body of an HTTP POST request or as the "xml" parameter of an HTTP GET request.

Supported output formats:

  • JSON (default) - The HTTP response will be a JSON-formatted Route Response.
  • XML - The HTTP response will be an XML-formatted Route Response.

Common URL Parameters

The following table describes the request parameters which are not related to specific Route Request options. These parameters, if supplied, must be supplied as request parameters (they can not be supplied in the BODY of the request).

Request Parameter Description
ambiguities
String
Use this parameter to set the strategy for resolving ambiguous location names.

  • ignore - the Routing Service will simply use the first location found for an address.
  • check - the Routing Service will return a full list of the possible location matches in the collections attribute of the response.
Default = 'ignore'
inFormat Specifies the format of the request. If this parameter is not supplied, the input format is assumed to be JSON-formatted text. The JSON-formatted input text must be supplied as either the "json" parameter of an HTTP GET, or as the BODY of an HTTP POST. If this parameter is "xml", the XML-formatted input text must be supplied as either the "xml" parameter of an HTTP GET, or as the BODY of an HTTP POST.

Must be one of the following, if supplied:
  • json
  • xml
Defaults to 'json' when using POST; otherwise it determines which to use based on parameters given.
json This parameter, if present, should contain the JSON-formatted text of the request. Use this parameter if you want to submit your request in JSON format, but do not want to use an HTTP POST to submit body text.

Note: Remember to URL-escape the text in this parameter!
xml This parameter, if present, should contain the XML-formatted text of the request. Use this parameter if you want to submit your request in XML format, but do not want to use an HTTP POST to submit body text.

Note: Remember to URL-escape the text in this parameter!
outFormat Specifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
Default = 'json'
callback A JavaScript function name. The JSON-formatted response will be wrapped in a call to the supplied callback function name to provide JSONP functionality. This functionality might be needed to do cross-site scripting. See the Wikipedia.org entry for JSON for more details.

Basic Routing Options

The following table describes the "bare bones" parameters needed to make a Route request:

Name Description
key
String
A unique key to authorize use of the Routing Service.

This is a required parameter!
from
Location
When the input format is Key/Value pairs, the starting location of a Route Request. Exactly one "from" parameter is allowed. This is used for locations only.
to
Location
When the input format is Key/Value pairs, the ending location(s) of a Route Request. More than one "to" parameter may be supplied. This is used for locations only.

Specifying Locations

A route request needs to contain a minimum of two locations, a start and end location. As mentioned above, a route request given in key/value pair format needs a from= and to= parameters with lat/lng locations. JSON and XML use two or more Lat/Lng Location objects, which are the same across all the services. Refer to the Locations documentation on how to properly form locations in all formats.

All route calls also have a validity check to prevent routes from becoming excessively long. This check uses a straight line (as the crow flies) distance between successive locations. The check adds the distance from location 0 to location 1, plus location 1 to location 2, etc. If this distance becomes more than 8000 miles, the service should return an Invalid Location result code with a message: "Exceeded maximum gross distance for locations."


Advanced Routing Options and Parameters

The section below describes different parameters that can be used in a Route Request.

Advanced Routing Options

The options in the table below, if used in a request in JSON or XML format, must be enclosed in a field named options. See the examples below for functional examples of the options field.

Note:These options might not be saved in the sessionId, so if you retrieve the saved request later (by supplying the sessionId parameter described above), you will have to ensure that you can recreate the options as needed.

Name Description
unit
String
Specifies the type of units to use when calculating distance. Acceptable values are:
  • m - Miles
  • k - Kilometers
Default = 'm'
routeType
String
Specifies the type of route wanted. Acceptable values are:
  • fastest - Quickest drive time route.
  • shortest - Shortest driving distance route.
  • pedestrian - Walking route; Avoids limited access roads; Ignores turn restrictions.
  • multimodal - Combination of walking and (if available) Public Transit.
  • bicycle - Bike route; Avoids limited access roads; Avoids roads where bicycle access is false; Favors bike specific paths and lower maxspeed roads.
Default = 'fastest'
doReverseGeocode
Boolean
If this flag is set, no reverse geocoding will be done on input locations. This is useful if, for instance, you are writing a mobile application and you know the exact latitude/longitude of your input locations, and you don't want to risk a reverse geocoding call which might change your latitude/longitude if an exact match is not found.
  • false - Input latitude/longitude will be used without any modification.
  • true - Even if exact latitude/longitude are given as input locations, a reverse geocode call will be performed to determine city/state/zipcode/etc.
Default = 'true'
narrativeType
String
Specifies the type of narrative to generate.
  • none - No narrative is generated
  • text - Standard text narrative
  • html - Adds some HTML tags to the standard text
  • microformat - Uses HTML span tags with class attributes to allow parts of the narrative to be easily styled via CSS. Explanation
Default = 'text'
enhancedNarrative
Boolean
Enhanced Narrative Option. This option will generate an enhanced narrative for Route & Alternate Route Services. This will encompass Intersection Counts, Previous Intersection, and Next Intersection/Gone Too Far advice.
  • false - No intersection counts, previous intersection, or Next Intersection/Gone Too Far advice will be displayed.
  • true - Intersection counts, previous intersection, and Next Intersection/Gone Too Far advice can be displayed when available.
Default = 'false'

Note: In order to view the proper maneuver note styles, the narrativeType needs to be set to 'microformat'. Microformat uses HTML span tags with class attributes to allow parts of the narrative to be easily styled via CSS. Read more.
maxLinkId
Integer
The maximum number of Link IDs to return for each maneuver. If zero, no Link ID data is returned.

Default = 0
locale
String
Examples of commonly used locale parameter values. Language to use in the narrative. Input can be any supported ISO 639-1 code.

English(US) = en_US(default)
English(Great Britain) = en_GB
French(Canada) = fr_CA
French(France) = fr_FR
Germany(Germany) = de_DE
Spanish(Spain) = es_ES
Spanish(Mexico) = es_MX
Russian(Russia) = ru_RU
Default = 'en_US'
avoids
String collection
Attribute flags of roads to try to avoid. The available attribute flags depend on the data set. This does not guarantee roads with these attributes will be avoided if alternate route paths are too lengthy or not possible or roads that contain these attributes are very short.

Available choices:
  • Limited Access - Highways
  • Toll Road
  • Ferry
  • Unpaved
  • Seasonal Closure - Approximate. Seasonal roads may not be selected with 100% accuracy.
  • Country Crossing
mustAvoidLinkIds
Integer Collection
Link IDs of roads to absolutely avoid. May cause some routes to fail. Multiple Link IDs should be comma-separated.
tryAvoidLinkIds
Integer Collection
Link IDs of roads to try to avoid during route calculation. Does not guarantee these roads will be avoided if alternate route paths are too lengthy or not possible. Multiple Link IDs should be comma-separated.
stateBoundaryDisplay
Boolean
State boundary display option.
  • true - State boundary crossings will be displayed in narrative.
  • false - State boundary crossings will not be displayed in narrative.
countryBoundaryDisplay
Boolean
Country boundary display option
  • true - Country boundary crossings are displayed in narrative.
  • false - Country boundary crossings are not displayed in narrative.
destinationManeuverDisplay
Boolean
The "End at" destination maneuver display option.
  • true - the "End at" destination maneuver is displayed in narrative.
  • false - the "End at" destination maneuver is not displayed in narrative.
fullShape
Boolean
This will return all shape (no generalization or clipping). This option overrides any mapState or generalize options.
  • true - All shape points will be returned.
  • false - Returned shape points depends on mapState or generalize options.


Default = false
shapeFormat
String
This option applies to both input and output (raw, cmp, cmp6) and overrides inShapeFormat and outShapeFormat.
Shape format options.
  • raw - shape is represented as float pairs.
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder.
inShapeFormat
String
Input shape format options.
  • raw - shape is represented as float pairs.
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder.
outShapeFormat
String
Output shape format options.
  • raw - shape is represented as float pairs.
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder.
generalize
Integer
If there is no mapState and fullShape = false, then the specified generalization factor will be used to generalize the shape.

If the generalize parameter is 0, then no shape simplification will be done and all shape points will be returned.

If the generalize parameter is > 0, it will be used as the tolerance distance (in meters) in the Douglas-Peucker Algorithm for line simplification.

Higher values of generalize will result in fewer points in the final route shape.
cyclingRoadFactor
Double
Sets the cycling road favoring factor. A value of < 1 favors cycling on non-bike lane roads. Values are clamped to the range 0.1 to 100.0

Default = 1.0
roadGradeStrategy
String
Specifies the road grade avoidance strategies to be used for each leg. This parameter is only for bicycle routes.
  • DEFAULT_STRATEGY - No road grade strategy will be used.
  • AVOID_UP_HILL - Avoid up hill road grades.
  • AVOID_DOWN_HILL - Avoid down hill road grades.
  • AVOID_ALL_HILLS - Avoid all hill road grades.
  • FAVOR_UP_HILL - Favor up hill road grades.
  • FAVOR_DOWN_HILL - Favor down hill road grades.
  • FAVOR_ALL_HILLS - Favor all hill road grades.
Default = 'DEFAULT_STRATEGY'
drivingStyle
Integer or String
Driving style to be used when calculating fuel usage.
  • 1 or cautious - Assume a cautious driving style.
  • 2 or normal - Assume a normal driving style. This is the default.
  • 3 or aggressive - Assume an aggressive driving style.
highwayEfficiency
Double
This is the fuel efficiency of your vehicle, given as miles per gallon. Valid range is 0 – 235 mpg. If a value is entered that is less than the minimum range, then 0 will be used. If a value is entered that is greater than the maximum range, then 235 will be used.
manMaps
Boolean
Maneuver maps display option.
  • true - A small staticmap is displayed per maneuver with the route shape of that maneuver. The route response will return a mapUrl. See -mapUrl in the Route Response section for a detailed description.
  • false - A small staticmap is not displayed per maneuver.
Default = true
walkingSpeed
Double
This is the speed (in miles per hour as default and it does adhere to the unit specifier) allowed for pedestrian routeTypes (or walking portions of a multimodal route). This is used for computing expected route times for walking routes. It is also used when computing multimodal routes. Since multimodal routes use date/time and schedule based departures and arrivals from transit stops, the speed which one walks can alter the suggested route.
The default is 2.5 miles per hour.

Advanced Routing Parameters

The following table describes the advanced parameters which can be used to make a Route request. These parameters would not be put inside an options object.

Name Description
sessionId
String
A unique identifier used to refer to a session. An existing session ID will be used if provided, otherwise a new one will be created. The route stored in the session will be automatically updated if the session ID is provided. Expires after 30 minutes.

This parameter is required for the Route Shape requests, but is optional for other requests.
mapState A mapState object, to which route shape information (if returned) will be mapped. Contains the basic information necessary to draw a map.

This parameter must contain the following information:
  • width (pixels)
  • height (pixels)
  • center (lat/lng of map center)
  • scale (map scale)
Note: Only width & height are required for Route and OptimizedRoute. All parameters are required for RouteShape.
mapState with width and height only: Specifying just mapWidth and mapHeight in the supplied mapState will result in shape points being generalized with an optimal tolerance based on the bestFit recommended zoom level. This option can be used to retrieve a route with shape optimized for the best fit center and zoom level to fit the route.
Full mapState: If a complete mapState is provide with center, width, height, and scale, the route shape will be clipped and generalized to the provided mapState. Be careful using this option as there is no guarantee the route shape will even be contained within the mapState (resulting in no shape points being returned). Another danger is "over-generalization" of the shape. This option should only be used if the current map will not be changed due to the new route.

To describe a mapState object using Key/Value pair input, supply the following query parameters:
  • mapWidth
  • mapHeight
  • mapScale or mapZoom - The scale factor of the map. If mapZoom is provided, it will override the value of mapScale. See Zoom to Scale Mapping for information on scales versus zoom levels.
  • mapLat
  • mapLng
mapLat and mapLng represent the latitude and longitude of the center of the map.

For sample JSON or XML input, see the sample response values below.


Advanced Routing Sample

The following example demonstrates the use of all the parameters provided and can generate both the Directions and Elevation (using the Open Elevation Service) of the route. When generating the Elevation Chart, please limit yourself to approximately 250 miles/400 kilometers.


Option Value(s) Notes
From:
To:
Avoids: Limited Access   Toll Road   Seasonal Closure   Unpaved   Ferry   Country border crossing
Route Type:
Time Type:  
Date Type:  
Date (MM/DD/YYYY):  
Time (hh:mm):  
Narrative Type:  
Enhanced Narrative:  
Do Reverse Geocode:  
Unit:  
Shape Format:  
Generalize: Ignored if "Shape Format" above is "none"
Input Format:  
Output Format:  
Locale:  
Ambiguities: Changes the "From" field (above).
Driving Style:
Highway Efficiency:
Units are miles/gallon.

(Output will be displayed below)    


Route Control Points

This is another extension of the Advanced Routing Options that allows the user to influence a regular route using a collection of route control points. To learn more about this feature, refer to the Route Control Points Documentation.


Route Response

The following table describes the response from a Route Request. The examples are given in JSON & XML format.

Response Field Description JSON Example Return Value(s) XML Example Return Value(s)
bestFit If a mapState is set, the directions service will compute and return new scale, zoom level, and center values that "best fit" the route shape. The best fit response will contain the original mapState height, width and scale as well as a new scale, new center and new level/zoom. It will use original mapState to calculate the new scale, new center and new level/zoom.
"bestFit": {
   "scale": 324767,
   "height": 3000,
   "newScale": 49873,
   "newCenter": {
      "lng": -76.431159,
      "lat": 40.0284
   },
   "width": 4000,
   "margin": 0,
   "newLevel": 13},
"mapState": {
   "center": {
      "lng": -76.4607,
      "lat": 39.988 },
   "scale": 324767,
   "height": 3000,
   "width": 4000},
            
            
<bestFit>: {
   <scale>: 324767,
   <height>: 3000,
   <newScale>: 49873,
   <newCenter>: {
      <lng>: -76.431159,
      <lat>: 40.0284
   },
   <width>: 4000,
   <margin>: 0,
   <newLevel>: 13},
<mapState>: {
   <center>: {
      <lng>: -76.4607,
      <lat>: 39.988 },
   <scale>: 324767,
   <height>: 3000,
   <width>: 4000},             
            
hasTollRoad A route attribute flag that is set per route and per leg. Per route, it returns true if at least one leg contains a Toll Road attribute, otherwise it returns false. Per leg, it returns true if at least one maneuver contains a Toll Road attribute, otherwise it returns false.
hasTollRoad: true
<hasTollRoad>true</hasTollRoad>
hasFerry A route attribute flag that is set per route and per leg. Per route, it returns true if at least one leg contains a Ferry attribute, otherwise it returns false. Per leg, it returns true if at least one maneuver contains a Ferry attribute, otherwise it returns false.
hasFerry: false
<hasFerry>false</hasFerry>
hasHighway A route attribute flag that is set per route and per leg. Per route, it returns true if at least one leg contains a Limited Access/Highway attribute, otherwise it returns false. Per leg, it returns true if at least one maneuver contains a Limited Access/Highway attribute, otherwise it returns false.
hasHighway: true
<hasHighway>true</hasHighway>
hasSeasonalClosure A route attribute flag that is set per route and per leg. Per route, it returns true if at least one leg contains a Seasonal Closure attribute, otherwise it returns false. Per leg, it returns true if at least one maneuver contains a Seasonal Closure attribute, otherwise it returns false.
hasSeasonalClosure: false
<hasSeasonalClosure>
	false
</hasSeasonalClosure>
hasUnpaved A route attribute flag that is set per route and per leg. Per route, it returns true if at least one leg contains an Unpaved attribute, otherwise it returns false. Per leg, it returns true if at least one maneuver contains an Unpaved attribute, otherwise it returns false.
hasUnpaved: false
<hasUnpaved>false</hasUnpaved>
hasCountryCross A route attribute flag that is set per route and per leg. Per route, it returns true if at least one leg contains a Country Crossing attribute, otherwise it returns false. Per leg, it returns true if at least one maneuver contains a Country Crossing attribute, otherwise it returns false.
hasCountryCross: false
<hasCountryCross>false</hasCountryCross>
boundingBox Returns lat/lng bounding rectangle of all points in the latlng collection; Returns the best-fit for route shape.
ul - a LatLng representing the upper-left LatLng
lr - a LatLng representing the lower-right LatLng
            
boundingBox: {
   ul: {
      lng: -76.734664,
      lat: 40.063175
   },
   lr: {
      lng: -76.306892,
      lat: 39.960338
   }
}
            
<boundingBox>
   <ul>
      <lat>40.063175</lat>
      <lng>-76.734664</lng>
   </ul>
   <lr>
      <lat>39.960338</lat>
      <lng>-76.306892</lng>
   </lr>
</boundingBox>
time Returns the calculated elapsed time in seconds for the route.
time: 2183
<time>2183</time>
formattedTime Returns the calculated elapsed time as formatted text in HH:MM:SS format.
formattedTime: 00:36:38
<formattedTime>
   00:36:38
</formattedTime>
distance Returns the calculated distance of the route.
distance: 25.150
<distance>25.150</distance>
fuelUsed The estimated amount of fuel used during the route
fuelUsed: 8.21
<fuelUsed>8.21</fuelUsed>
legs A collection of leg objects, one for each "leg" of the route.
legs: [...]
<legs>...</legs>
leg Describes one "leg" of a route. It contains the maneuvers describing how to get from one location to the next location.

Each leg will contain a variety of information, including an index, time, distance, and formattedTime.
{
 index": 0,
"distance": 28.734,
"time": 2340,
"origIndex": 1,
"hasSeasonalClosure": false,
"origNarrative": "Go west on US-30 W.",
"hasCountryCross": false,
"formattedTime": "00:39:00",
"destNarrative": "Proceed to YORK, PA.",
"destIndex": 2,
          maneuvers: [
               ...
          ]
       }
<leg>
   <distance>
      25.93
   </distance>
   <time>
      2359
   </time>
   <formattedTime>
      00:39:19
   </formattedTime>
   <index>0</index>
   <maneuvers>
      ...
   </maneuvers>
</leg>
Collapsed Narrative Parameters The origin parameters are used if the user is familiar with the area and wants to collapse/hide the first few steps of the Route Narrative. The destination parameters are used if the user is familiar with the area and wants to collapse/hide the last few steps of the Route Narrative. Please note that this is currently only in the json response, not xml. An example of this is displayed on www.mapquest.com. See/Click the "I know the area, hide the first few steps" or "I know the area, hide the last few steps".
  • origIndex - The origin index is the index of the first non-collapsed maneuver.
  • origNarrative - The rephrased origin narrative string for the first non-collapsed maneuver.
  • destIndex - The destination index is the index of the last non-collapsed maneuver.
  • destNarrative - The rephrased destination narrative string for the destination maneuver.
{
"origIndex": 5,
"origNarrative": "Go west on US-30 W.",
"destNarrative": "Proceed to YORK, PA."
"destIndex": 5
}
maneuvers A collection of Maneuver objects
maneuvers: []
<maneuvers></maneuvers>
maneuver Describes one step in a route narrative. Contains narrative, street names, m_shape, linkIds, route type, turnType, m_distance, m_time, direction, attributes, signs. See descriptions below. (Name is abstract for JSON...)
<maneuver></maneuver>
signs Returns text name, extra text, type (road shield), and direction present for a particular maneuver. Also returns the URLs for the sign images.
Signs: [
   text: "30", 
   extraText: "", 
   direction: 7, 
   type: 2, 
   url: http://...
            
<signs>
   <sign>
      <text> "30"</text>
      <extraText> ""</extraText>
      <direction> 7 </direction>
      <type> 2 </type>
      <url>http:///...
   </sign>
</signs>
mapUrl Returns a URL to a static map of this maneuver.
mapUrl:/staticmap/v4/getmap?type=map&size=225, 160&pois=purple-1,39.960338,-76.734664,0,0|purple-2,39.968059,-76.711906,0,0|¢er=39.964198499999995,
-76.723285&zoom=11&key=YOUR_KEY_HERE&rand=1568433620&session=4aba4bd6-0074-0000-02b7-0e4d-0024e83e211d
<mapUrl>
/staticmap/v4/getmap?type=map&size=225,
160&pois=purple-1,39.960338,-76.734664,0,0|purple-2,39.968059,-76.711906,0,0|
&center=39.964198499999995,-76.723285&zoom=11&key=YOUR_KEY_HERE&rand=1568433620
&session=4aba4bd6-0074-0000-02b7-0e4d-0024e83e211d</mapUrl>
narrative Returns textual driving directions for a particular maneuver.
narrative: "Start out going 
NORTHWEST on GRANITE RUN DR 
toward CARERRA DR."
<narrative>
   Start out going NORTHWEST on 
   GRANITE RUN DR toward 
   CARERRA DR.
</narrative>
maneuverNotes A collection of maneuverNote objects, one for each maneuver.

Note: In order to view the proper maneuver note styles, the narrativeType needs to be set to 'microformat'. Microformat uses HTML span tags with class attributes to allow parts of the narrative to be easily styled via CSS. Read more.
maneuverNotes: [...]
<maneuverNotes>...</maneuverNotes>
ruleId A unique ID that is assigned to a particular maneuver note. This rule ID is used to determine the order that the maneuver notes will be displayed in the narrative. When enhancedNarrative=true, the possible return values are:
  • Previous Intersection = 1
  • Place holders for future notes = 2,3
  • Next Intersection/Gone Too Far = 4
  • Timed Restrictions = 5
When enhancedNarrative=false, the possible return values are:
  • Timed Restrictions = 1
ruleId: 5
<ruleId>5</ruleId>
manNote Returns the maneuver note for a particular maneuver. Maneuver notes can exist for Timed Turn Restrictions, Timed Access Roads, HOV Roads, Seasonal Closures, and Timed Direction of Travel. Please Note: When the enhancedNarrative flag is set to true, additional maneuver notes may be displayed (see Route Option: enhancedNarrative).
{
   manNote: "Timed driving
	access restriction:
		SUN 7AM to MIDNIGHT" 
},
{   
   manNote: "Timed driving
	access restriction:
		SAT MIDNIGHT to 7PM" 
}
<manNote>
   Timed driving access restriction:
	SUN 7AM to MIDNIGHT
</manNote>
<manNote>
   Timed driving access restriction:
	SAT MIDNIGHT to 7PM
</manNote>
manNoteType Used to specify the type of maneuver note. Possible return values are:
  • Previous Intersection = 24
  • Next Intersection = 25
  • Gone Too Far End = 26
  • Timed Restrictions = 10 - 14
manNoteType: "10".
<manNoteType>"10"</manNoteType>
direction Returns the direction associated to a particular maneuver. Possible return values are:
  • none = 0
  • north = 1
  • northwest = 2
  • northeast = 3
  • south = 4
  • southeast= 5
  • southwest = 6
  • west = 7
  • east = 8
direction: 2
<direction>2</direction>
streets Returns the collection of street names this maneuver applies to.
             
streets: [
   "GRANITE RUN DR", 
   "CARERRA DR"
]
             
<streets> 
   <street>
      "GRANITE RUN DR"
   </street>
   <street>
      "CARERRA DR"
    </street>
</streets>
attributes Returns the attributes associated to a particular maneuver. Possible return values are:
  • none = 0
  • portions toll = 1
  • portions unpaved = 2
  • possible seasonal road closure = 4
  • gate = 8
  • ferry = 16
  • avoid id= 32
  • country crossing = 64
  • limited access (highways) = 128
attributes: [0]
<attributes> 
   <attribute>0</attribute>
</attributes>
turnType Returns the turn type associated to a particular maneuver. Possible return values are:
  • straight = 0
  • slight right = 1
  • right = 2
  • sharp right = 3
  • reverse = 4
  • sharp left = 5
  • left = 6
  • slight left = 7
  • right u-turn = 8
  • left u-turn =9
  • right merge =10
  • left merge = 11
  • right on ramp = 12
  • left on ramp = 13
  • right off ramp = 14
  • left off ramp = 15
  • right fork = 16
  • left fork = 17
  • straight fork = 18
turnType: 1
<turnType>1</turnType>
startPoint Returns the 1st shape point latLng for a particular maneuver. This will allow for zoomed street functionality for a maneuver.
          
startPoint: {
   lng: -76.734664,
   lat: 39.960338
}
             
<startPoint>
   <lng>-76.734664</lng>
   <lat>39.960338</lat>
</startPoint>
location Returns a collection of locations in the form of an address. See the Specifying locations as JSON/XML section for more detail on the format of a Location object.
location: []
<location></location>
sessionId Returns a unique identifier used to refer to a session. An existing session id will be used if provided, otherwise a new one will be created. The route stored in the session will be automatically updated if the session id is provided. Expires after 30 minutes.
sessionId: "12345..."
<sessionId>
   12345...
</sessionId>
mapState Used to get the route shape from a session.
mapState: {
   center: {
      lng: -76.4607,
      lat: 39.988
   }
   scale: 324767
   height: 3000
   width: 4000
}
<mapState>
   <center>
      <lng>
         -76.4607
      </lng>
      <lat>
         39.988
      </lat>
   </center>
   <scale>324767</scale>
   <height>3000</height>
   <width>4000</width>
</mapState>
shapeFormat The shape format options:
  • raw - shape is represented as float pairs
  • cmp - shape is represented as a compressed path string; See - http://soulsolutions.com.au/Default.aspx?tabid=96 for a detailed description of the compressed format
  • none - No shape will be returned. In this case, the generalize parameter will be ignored.
shapeFormat: "raw"
<shapeFormat>raw</shapeFormat>
shape A collection of latitude/longitude coordinates or shape points for the entire route highlight based on original mapstate and/or the generalize option. Shape is an alternated array of lat/lngs. Evens are lat and odds are lng.

Also included will be:
  • legIndex - An array of the starting index of each leg, and
  • maneuverIndex - An array of the starting index for each maneuver.
Each leg / maneuver object in the Route response has an index attribute which corresponds to the entry in the legIndex / maneuverIndex array.
"shape": {
"maneuverIndexes": [
   0,
   2,
   8
],
"shapePoints": [
   40.001415,
   -76.850395,
   39.991413,
   -76.840629,
   39.98516,
   -76.82817,
   39.97805,
   -76.79705,
   39.974239,
   -76.787254,
   39.967002,
   -76.776916,
   39.956775,
   -76.746009,
   39.960338,
   -76.734664
],
"legIndexes": [
   0,
   9
]
},
            
<shape>
   <shapePoints>
      <latLng>
         <lat>40.001415</lat>
         <lng>-76.850395</lng>
      </latLng>
      <latLng>
         <lat>39.991413</lat>
         <lng>-76.840629</lng>
      </latLng>
      <latLng>
         <lat>39.98516</lat>
         <lng>-76.82817</lng>
      </latLng>
      <latLng>
         <lat>39.97805</lat>
         <lng>-76.79705</lng>
      </latLng>
      <latLng>
         <lat>39.974239</lat>
         <lng>-76.787254</lng>
      </latLng>
      <latLng>
         <lat>39.967002</lat>
         <lng>-76.776916</lng>
      </latLng>
      <latLng>
         <lat>39.956775</lat>
         <lng>-76.746009</lng>
      </latLng>
      <latLng>
         <lat>39.960338</lat>
         <lng>-76.734664</lng>
      </latLng>
   </shapePoints>
   <legIndexes>
      <index>0</index>
      <index>9</index>
   </legIndexes>
   <maneuverIndexes>
      <index>0</index>
      <index>2</index>
      <index>8</index>
   </maneuverIndexes>
</shape>
legIndexes The shape point index which starts a specific route segment. The shape point index of the end of the segment is legIndex-1 of the next legIndex.Note that there is always one extra legIndex (the number of legIndexes = number of legs + 1) to account for the last shape point of the final segment. See shape See shape
shapePoints Shape points for the route (clipped and generalized) will be returned if mapState is given. Shape points is an alternated array of lat/lngs. Evens are lat and odds are lng. The index of a specific shape point is i/2. See shape See shape
options Routing options
            
options: {
   avoids: ['Limited Access','Toll Road'],
   mustAvoidLinkIds: [12345, 54321],
   tryAvoidLinkIds: [19720821],
   type:  'fastest', 
   locale: 'en_US',
   unit: 'm' 
}
            
<options>
   <avoids>
      <avoid>
         Limited Access
      </avoid>
      <avoid>
         Toll Road
      </avoid>
   </avoids>
   <mustAvoidLinkIds>
       1234, 4321
   </mustAvoidLinkIds>
   <tryAvoidLinkIds>
       19720821
   </tryAvoidLinkIds>
   <type> 'fastest' </type> 
   <locale> 'en_US' </locale>
   <unit> 'm' </unit> 
</options>
avoids Attribute flags of roads to try to avoid. The available attribute flags depend on the data set. This does not guarantee roads with these attributes will be avoided if alternate route paths are too lengthy or not possible or roads that contain these attributes are very short.
            
avoids: [
   "Limited Access",
   "Toll Road"
]
            
<avoids>
   <avoid>
      Limited Access
   </avoid>
   <avoid>
      Toll Road
   </avoid>
</avoids>
mustAvoidLinkIds Returns link Ids of roads that will be absolutely avoided. May cause some routes to fail.
mustAvoidLinkIds: [
   12345, 54321
]
            
<mustAvoidLinkIds>
   12345, 54321
</mustAvoidLinkIds>
tryAvoidLinkIds Returns link Ids of roads that we will try to avoid during route calculation. Does not guarantee these roads will be avoided if alternate route paths are too lengthy or not possible.
tryAvoidLinkIds: [
   12345, 54321
]
            
<tryAvoidLinkIds>
   12345, 54321
</tryAvoidLinkIds>
routeType The type of route:
  • fastest - Quickest drive time route.
  • shortest - Shortest driving distance route.
  • pedestrian - Walking route; Avoids limited access roads; Ignores turn restrictions. Note: There is a distance limit (approximately 200 miles / 320 kilometers) for pedestrian routing. Requests to find a pedestrian route beyond the maximum distance will result in an error.
  • multimodal - Combination of walking and (if available) Public Transit. Note: You must supply time information, because multimodal routes are implicitly time-sensitive.
  • bicycle - Bike route; Avoids limited access roads; Avoids roads where bicycle access is false; Favors bike specific paths and lower maxspeed roads.
routeType: "fastest"
<routeType>'fastest'</routeType>
locale Language to use in the narrative.
locale: "en_US"
<locale>en_US</locale>
unit Specifies the type of units to use when calculating distance.
unit: "M"
<unit>M</unit>
info This field contains information about the response.

The statuscode subfield is an integer return value. See the status codes page for more details on our status codes and error messages.

The messages subfield is an array of error messages which describe the status.
            
info:{
   statuscode: 0,
   messages: [
      "200 Unable to calculate route."
   ]
}
<info>
   <statuscode>
      0
   </statuscode>
   <messages>  
      200 Unable to 
      calculate route. 
   </messages>
</info>
transportMode This is a string indicating the mode of transportation used for the maneuver. Values include: "AUTO", "WALKING", "BICYCLE", "RAIL", "BUS" (future use).

            

            
filterZoneFactor This is returned in the response as part of the options and represents an internal route options used in alternate routes. It cannot be set as an input by the application but can be used to differentiate 2 alternate route results.

            

            

Optimized Route Options

An Optimized Route request uses the "optimizedRoute" routing method. The request is sent with the Route Request parameters and finds the route with the most optimized drive time / shortest distance / walking time that includes all intermediate locations. The origin and destination locations remain fixed, but the intermediate locations are re-ordered to find the optimal path through the set of locations.

The Optimized Route response is similar to a regular Route response except that in an Optimized Route response, the sort order among the intermediate locations may change and there is an additional response field called locationSequence that gets returned. Optimized routes are limited to 25 locations.

The table below describes the Optimized Route response differences from a regular Route response.

Response Field Description
locationSequence Returns a sequence array that can be used to determine the index in the original location object list.
locations Returns a collection of locations in the form of an address. The origin and destination locations remain fixed, but the intermediate locations are re-ordered as appropriate.

Note that the locationSequence and locations response values have been reordered from the input.

JSON Sample Response XML Sample Response
...                
locationSequence: [
   0,2,1,3
],
locations:[
{
   latLng: {
    	lng: -0.129892,
    	lat: 51.52441
	}, 
	latLng: {
    	lng: -0.149547,
    	lat: 51.520618
	},  
    latLng: {
    	lng: -0.165188,
    	lat: 51.544959
	},  
    latLng: {
    	lng: -0.201705,
    	lat: 51.528506
	}
]
...
...
<locationSequence>
   0,2,1,3
</locationSequence>
<locations>
   <location>
     <latLng>
	   <lat>51.5245</lat> 
	   <lng>-0.1299</lng>
	 </latLng> 
   </location> 
      <location>
     <latLng>
	   <lat>51.5207</lat> 
	   <lng>-0.1496</lng>
	 </latLng> 
   </location> 
      <location>
     <latLng>
	   <lat>51.5450</lat> 
	   <lng>-0.1652</lng>
	 </latLng> 
   </location> 
      <location>
     <latLng>
	   <lat>51.5286</lat> 
	   <lng>-0.2018</lng>
	 </latLng> 
   </location> 
</locations>
...

Optimized Route Sample

Optimized Routing is designed to support optimized paths through locations that are relatively close to each other: e.g., planning delivery or repair services, planning a tour of Open houses, etc. It will attempt to Optimize longer distance paths, but to meet performance limits it may estimate drive time based on distance, which may lead to slightly less than optimal paths.

Imagine you are a traveling salesman, covering all of central Pennsylvania. You are about to embark on a trip to visit your favorite towns: Boalsburg, York, State College, and Lancaster.

How do you optimize your trip so you can hit all the stops on your trip in the least time? Simple: You use the MapQuest Routing Platform APIs to request an optimized route!

Notice in the example below how the optimized route will reorder the stops on your route, even though the locations are entered in the same order as the normal route request.


Route Type: Optimized
Normal

(Route will be displayed below)


Route Matrix Options

A Route Matrix request allows quick and easy calculation of the distances and driving times between a set of points.

Input to a Route Matrix request is:

  1. A list of at least two Locations, as with a normal Route request
  2. An optional boolean parameter named allToAll. If this parameter is not present, or false, the response will contain a one-dimensional list of times/distances from the first location to each location. If the allToAll parameter is set to true, the response will contain a two-dimensional list of times/distances from each location to every other location.
  3. An optional boolean parameter named manyToOne. If this parameter is not present, or false, the response will contain a one-dimensional list of times/distances from the first location to each location. If the manyToOne parameter is set to true, this indicates that the method will compute time and distance from many origins to a single destination (the first location in lc). This flag is only valid if allToAll is false.
The distance from a location to itself will be a small but non-zero distance.

Note that time/distances values are not always symmetric. That is, the distance from A to B might not be the same as the distance from B to A.

Response Field Description
allToall The allToAll parameter, echoed for clarity.
manyToOne The manyToOne parameter, echoed for clarity.
distance An array of distances between Locations. The array will have dimension 1xN (where N is the number of Locations supplied) if the allToAll parameter was false, or NxN otherwise. When allToAll is false, element i of the array will be the distance from the first Location to location i. When allToAll is true, element i,j of the array will be the distance from location i to location j.
time An array of times (in seconds) between Locations. The array will have dimension 1xN (where N is the number of Locations supplied) if the allToAll parameter was false, or NxN otherwise. When allToAll is false, element i of the array will be the time from the first Location to location i. When allToAll is true, element i,j of the array will be the time from location i to location j.
locations Same as with a normal Route response
info Information block, containing a statusCode and a (possibly empty) list of messages

Route Matrix Limits

There are time and distance limits in place on the route matrix call because this can become a very expensive request. The route matrix is not intended for computing extremely long distances from a large number of locations.

  • A One to Many route matrix call can handle up to 100 locations.
  • A Many to One matrix call can handle up to 50 locations.
  • An all to all route matrix call can handle up to 25 locations.
  • Route matrix methods use what is called multi-destination path search. It expands from the origin location and marks each destination it finds. This search gets more expensive as the distance from the origin location increases, so the search is limited by a setting called MaxMatrixSearchTime. This is set to 180 minutes. Any destinations that lie outside this limit are found using regular "point to point" routes. However, the server limits the number of outlying locations (outside the MaxMatrixSearch limit) with a setting called MaxMatrixPointToPoint. This value is set to 25. Route matrix methods are intended to support many destinations within a short distance of each other. These limits allow several locations to be further away, but still protect the server from matrix requests that would take an exceptionally long time to compute. A user should break such requests into smaller sets to allow them to complete within the limits.

Route Matrix Sample Responses

JSON Sample Response XML Sample Response
                
{
   allToAll: false,
   distance: [
      0,
      25.685,
      107.846,
      78.452
   ],
   time: [
      0,
      2260,
      7253,
      5930
   ],
   locations: [
      "Lancaster, England",
      "Liverpool, England",
      "Chester, England",
      "Stoke-on-Trent, England"
   ],
   info: {
      ...
   }
}               
                
<response>
   <allToAll>false</allToAll>
   <distance>
      0,
      25.685,
      107.846,
      78.452
   </distance>
   <time>
      0,
      2260,
      7253,
      5930
   </time>
   <locations>
      <location>Lancaster, England</location>
      <location>Liverpool, England</location>
      <location>Chester, England</location>
      <location>Stoke-on-Trent, England</location>
   </locations>
   <info>
      ...
   </info>
</response>      

Route Matrix Example


allToAll? No
Yes

(Route Matrix results will be displayed below)    


Route Shape Options

Route Shape requests allow you to quickly retrieve the shape from a previous route request, without having to send another Route request.

To perform a RouteShape request, you must perform the following two steps:

  1. Do a normal Route request. The RouteResponse from this request will include a sessionId attribute.
  2. Send a RouteShape request, and include the sessionId returned in step (1). NOTE: You must either supply a mapState object describing the map to which you want the shape to be mapped.
    or use the fullShape and generalize parameters.
The return value from the RouteShape request will contain a shape attribute, which will in turn contain a shapePoints attribute. The shapePoints will be clipped as appropriate for the mapState provided in the request.

Route Shape Example

Step 1: Get a new route:

From:
To:
To (optional):
To (optional):
To (optional):

(Route results will be added to list below)

Step 2: Request the shape from a previous route:

[No known routes yet...]



Drag Route Options

Drag Route requests are variants of simple Route requests. Drag Route requests allow a route to be recalculated "on the fly" by quickly inserting a new Location into the list of existing Locations

A Drag Route request must contain, at a minimum:

  1. Exactly one Location object with its dragPoint attribute set to true
  2. A valid mapState object, to which the resulting route will be mapped
It is strongly suggested that all Location objects have valid linkId attributes. The easiest way to get a valid linkId for a Location is to use the value returned from a previous Route request. If you do not provide a linkId for a Location, your Drag Route request might fail. For instance, when a location is supplied with a lat/lng value and dragPoint set to true, but the location can not be mapped to a nearby road, the Drag Route request will fail. Make sure you check the info attribute of the response from your Drag Route request.

The response from a Drag Route request will contain a new route, which will be routed (if possible) through the locations supplied. The response will not contain narrative information, but will include route shape information.

Note that the value of the route attribute from the output of a Drag Route request is valid as input to a Route request. This allows you do make multiple Drag Route requests to reshape your route as desired, before making another Route request to get an updated Route narrative.

Drag Route Example

In the sample below, drag the route to display the Drag Route request being sent to the MapQuest servers during the drag.


Find Link Id

One can find a link id by inputting a latitude and longitude. The returned link id could be supplied with the mustAvoidLinkIds or the tryAvoidLinkIds route option attribute.

Request Parameter Description Accepted Request Data Required
lat The latitude of the point to find a link id 39.9656 Yes
lng The longitude of the point to find a link id. -76.1843 Yes

The following example demonstrates a simple request to find a link id for a latitude/longitude of 39.9656,-76.1843. The JavaScript code which sends the request and displays the result can be viewed here.

Find Link Id Sample



Latitude: Longitude:

inFormat:

(Results will be displayed below)

  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use