Open Directions API

GET
Path From Route

The Path from Route function provides an easy method for searching along the corridor defined by a route. The function provides the times/distances needed to reach a set of Locations from an existing route.

Resource URL

http://open.mapquestapi.com/directions/v2/pathfromroute

Resource Information

Response Formats JSON, XML
Authentication Yes (Requires Key)
Rate Limited Yes

Request Parameters

Request Parameter Description Required?
key
String
The API Key, which is needed to make requests to MapQuest services. Yes
sessionId The sessionId associated with the base route upon which you want to base your request. Yes
points A list of lat/lng pairs which define the points to which you want to calculate the time/distance from the base route.

The format of the points argument should match the shapeFormat parameter of the route options See the shapeFormat and Encoded Shape Points documentation for more details.

Default: raw
Yes
maxDistance
or
maxTime
The maximum distance or time you are willing to travel off the base route to reach a location.

If maxDistance is supplied, the units are assumed to match those of the unit option (default: miles), and a route type of shortest will be applied.

If maxTime is supplied, the units are assumed to be seconds, and a route type of fastest will be applied.

Note: You must supply either maxDistance or maxTime, but not both.
Yes
outFormat Specifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
Default: json
No
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. No

Response

Response Field Description
times An array of integer values, corresponding to the time (in seconds) needed to reach each point from the base route. This array will be the same length as the number of locations passed to this call in the points input parameter.

If the value for a location is 0, the location is close enough to the route to be considered "on" the route.

If the value is -1, the location can not be reached within the input time/distance constraint.
distances An array of floating point values, corresponding to the distance (in miles or kilometers, as defined by the unit parameter of the request option) to each point from the base route. This array will be the same length as the number of locations passed to this call in the points input parameter.

If the value for a location is 0, the location is close enough to the route to be considered "on" the route.

If the value is -1, the location can not be reached within the input time/distance constraint.
exitLatLngs An array of lat/lng pairs, corresponding to the exit points where a route would diverge from the base route to reach each location. The length of this array will be exactly double the number of locations passed to this call in the points input parameter.

If a location is not reachable, it will have a lat/lng of 0/0.
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.

If none of the locations supplied in the points input parameter are reachable within the given time/distance contraint, the times, distances, and exitLatLngs arrays will be empty. In this case, consult the info return object for a more detailed explanation of the return.

Example Request

GET

http://open.mapquestapi.com/directions/v2/pathfromroute?key=KEY&sessionId=SESSION_ID&maxTime=5&points=40.289309,-76.647958,40.258014,-76.569789&unit=m&shapeFormat=raw

{
  "exitLatLngs": [
    40.285514,
    -76.650619,
    0,
    0
  ],
  "times": [
    125,
    -1
  ],
  "distances": [
    0.641,
    -1
  ],
  "info": {
    "copyright": {
      "text": "© 2017 MapQuest, Inc.",
      "imageUrl": "http://api.mqcdn.com/res/mqlogo.gif",
      "imageAltText": "© 2017 MapQuest, Inc."
    },
    "statuscode": 0,
    "messages": []
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <info>
        <statusCode>0</statusCode>
        <messages/>
        <copyright>
            <imageUrl>http://api.mqcdn.com/res/mqlogo.gif</imageUrl>
            <imageAltText>© 2017 MapQuest, Inc.</imageAltText>
            <text>© 2017 MapQuest, Inc.</text>
        </copyright>
    </info>
    <times>125,-1</times>
    <distances>0.641,-1</distances>
    <exitPoints>
        <latLng>
            <lat>40.285514</lat>
            <lng>-76.650619</lng>
        </latLng>
        <latLng>
            <lat>0.0</lat>
            <lng>0.0</lng>
        </latLng>
    </exitPoints>
</response>