Open Directions API

GET
Route Shape

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 Route Shape request, you must perform the following two steps:

  1. Send a normal Route request. The RouteResponse from this request will include a sessionId attribute.
  2. Send a Route Shape request, and include the sessionId returned in step 1.

You must also either supply a mapState object describing the map to which you want the shape to be mapped or use the fullShape and generalize parameters.

Resource URL

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

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
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)
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.
Yes, unless fullShape is specified.
fullShape Returns all shapes (no generalization or clipping). This option overrides any mapState or generalize options.
  • true - all shape points will be returned
  • false - returned shape points depend on mapState or generalizeoptions
Default: false
Yes, unless mapState is specified.
generalize 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.
No
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
shape A collection of latitude/longitude coordinates or shape points for the entire route highlight based on the original mapState and/or the generalize option. Shape is an alternated array of lat/lngs. Evens are latitudes and odds are longitudes.

Also included will be:
  • legIndexes - an array of the starting index of each leg
  • maneuverIndexes - an array of the starting index for each maneuver
Each leg and maneuver object in the Route response has an index attribute which corresponds to the entry in the legIndexes/maneuverIndexes array.
legIndexes Returns an array of the shape point index for each 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.
maneuverIndexes Returns an array of the starting index for each maneuver.
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 latitudes and odds are longitudes. The index of a specific shape point is i/2.
boundingBox Returns lat/lng bounding rectangle of all points in the latlng collection; Returns the best-fit for route shape.
  • ul - a lat/lng representing the upper-left lat/lng
  • lr - a lat/lng representing the lower-right lat/lng
options Returns route options for the route specified by the sessionId
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.

Example Request

GET

http://open.mapquestapi.com/directions/v2/routeshape?key=KEY&sessionId=SESSION_ID&mapWidth=320&mapHeight=240&mapScale=1733371&mapLat=40.491304&mapLng=-77.2614665

Example Response

{
  "route": {
    "boundingBox": {
      "ul": {
        "lng": -77.793266,
        "lat": 40.798587
      },
      "lr": {
        "lng": -76.729667,
        "lat": 40.203571
      }
    },
    "shape": {
      "maneuverIndexes": [
        0,
        2,
        4,
        6,
        8,
        10,
        12,
        14,
        16,
        18,
        20,
        22,
        52,
        54,
        55
      ],
      "shapePoints": [
        40.203735,
        -76.729667,
        40.203617,
        -76.729705,
        40.203617,
        -76.729705,
        40.203571,
        -76.733085,
        40.203571,
        -76.733085,
        40.212993,
        -76.735542,
        40.212993,
        -76.735542,
        40.222515,
        -76.753242,
        40.222515,
        -76.753242,
        40.222,
        -76.754974,
        40.222,
        -76.754974,
        40.227867,
        -76.757873,
        40.227867,
        -76.757873,
        40.227539,
        -76.761886,
        40.227539,
        -76.761886,
        40.221908,
        -76.783859,
        40.221908,
        -76.783859,
        40.249027,
        -76.812561,
        40.249027,
        -76.812561,
        40.304954,
        -76.83039,
        40.304954,
        -76.83039,
        40.301498,
        -76.872665,
        40.301498,
        -76.872665,
        40.364498,
        -76.92881,
        40.368495,
        -76.981414,
        40.382682,
        -77.016967,
        40.397239,
        -77.008132,
        40.430889,
        -77.010658,
        40.471801,
        -77.032135,
        40.480957,
        -77.049224,
        40.479011,
        -77.068656,
        40.493789,
        -77.082611,
        40.498321,
        -77.126365,
        40.526847,
        -77.134216,
        40.564601,
        -77.169754,
        40.57061,
        -77.243759,
        40.539234,
        -77.341888,
        40.556442,
        -77.362098,
        40.594371,
        -77.377586,
        40.611503,
        -77.445732,
        40.579284,
        -77.551391,
        40.622348,
        -77.580848,
        40.653442,
        -77.583488,
        40.668922,
        -77.604171,
        40.683479,
        -77.607658,
        40.703529,
        -77.597267,
        40.727935,
        -77.604621,
        40.732955,
        -77.63565,
        40.760101,
        -77.614212,
        40.794662,
        -77.625228,
        40.798587,
        -77.656425,
        40.779037,
        -77.771057,
        40.779037,
        -77.771057,
        40.778633,
        -77.793205,
        40.778633,
        -77.793205,
        40.777702,
        -77.793266
      ],
      "legIndexes": [
        0,
        56
      ]
    },
    "routeError": {
      "message": "",
      "errorCode": -400
    },
    "options": {
      "mustAvoidLinkIds": [],
      "drivingStyle": 2,
      "countryBoundaryDisplay": true,
      "generalize": -1,
      "narrativeType": "text",
      "locale": "en_US",
      "avoidTimedConditions": false,
      "destinationManeuverDisplay": true,
      "enhancedNarrative": false,
      "filterZoneFactor": -1,
      "timeType": 0,
      "maxWalkingDistance": -1,
      "routeType": "FASTEST",
      "transferPenalty": -1,
      "stateBoundaryDisplay": true,
      "walkingSpeed": -1,
      "maxLinkId": 0,
      "arteryWeights": [],
      "tryAvoidLinkIds": [],
      "unit": "M",
      "routeNumber": 0,
      "shapeFormat": "raw",
      "maneuverPenalty": -1,
      "useTraffic": false,
      "returnLinkDirections": false,
      "avoidTripIds": [],
      "manmaps": "true",
      "highwayEfficiency": 22,
      "sideOfStreetDisplay": true,
      "cyclingRoadFactor": 1,
      "urbanAvoidFactor": -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>
    <routeError>
        <errorCode>-400</errorCode>
        <message></message>
    </routeError>
    <route>
        <options>
            <shapeFormat>raw</shapeFormat>
            <generalize>-1.0</generalize>
            <maxLinkId>0</maxLinkId>
            <narrativeType>text</narrativeType>
            <stateBoundaryDisplay>true</stateBoundaryDisplay>
            <countryBoundaryDisplay>true</countryBoundaryDisplay>
            <sideOfStreetDisplay>true</sideOfStreetDisplay>
            <destinationManeuverDisplay>true</destinationManeuverDisplay>
            <avoidTimedConditions>false</avoidTimedConditions>
            <enhancedNarrative>false</enhancedNarrative>
            <returnLinkDirections>false</returnLinkDirections>
            <timeType>0</timeType>
            <routeType>FASTEST</routeType>
            <locale>en_US</locale>
            <unit>M</unit>
            <tryAvoidLinkIds></tryAvoidLinkIds>
            <mustAvoidLinkIds></mustAvoidLinkIds>
            <manmaps>true</manmaps>
            <drivingStyle>2</drivingStyle>
            <highwayEfficiency>22.0</highwayEfficiency>
            <useTraffic>false</useTraffic>
        </options>
        <boundingBox>
            <ul>
                <lat>40.798587</lat>
                <lng>-77.793266</lng>
            </ul>
            <lr>
                <lat>40.203571</lat>
                <lng>-76.729667</lng>
            </lr>
        </boundingBox>
        <shape>
            <shapePoints>
                <latLng>
                    <lat>40.203735</lat>
                    <lng>-76.729667</lng>
                </latLng>
                <latLng>
                    <lat>40.203617</lat>
                    <lng>-76.729705</lng>
                </latLng>
                <latLng>
                    <lat>40.203617</lat>
                    <lng>-76.729705</lng>
                </latLng>
                <latLng>
                    <lat>40.203571</lat>
                    <lng>-76.733085</lng>
                </latLng>
                <latLng>
                    <lat>40.203571</lat>
                    <lng>-76.733085</lng>
                </latLng>
                <latLng>
                    <lat>40.212993</lat>
                    <lng>-76.735542</lng>
                </latLng>
                <latLng>
                    <lat>40.212993</lat>
                    <lng>-76.735542</lng>
                </latLng>
                <latLng>
                    <lat>40.222515</lat>
                    <lng>-76.753242</lng>
                </latLng>
                <latLng>
                    <lat>40.222515</lat>
                    <lng>-76.753242</lng>
                </latLng>
                <latLng>
                    <lat>40.222</lat>
                    <lng>-76.754974</lng>
                </latLng>
                <latLng>
                    <lat>40.222</lat>
                    <lng>-76.754974</lng>
                </latLng>
                <latLng>
                    <lat>40.227867</lat>
                    <lng>-76.757873</lng>
                </latLng>
                <latLng>
                    <lat>40.227867</lat>
                    <lng>-76.757873</lng>
                </latLng>
                <latLng>
                    <lat>40.227539</lat>
                    <lng>-76.761886</lng>
                </latLng>
                <latLng>
                    <lat>40.227539</lat>
                    <lng>-76.761886</lng>
                </latLng>
                <latLng>
                    <lat>40.221908</lat>
                    <lng>-76.783859</lng>
                </latLng>
                <latLng>
                    <lat>40.221908</lat>
                    <lng>-76.783859</lng>
                </latLng>
                <latLng>
                    <lat>40.249027</lat>
                    <lng>-76.812561</lng>
                </latLng>
                <latLng>
                    <lat>40.249027</lat>
                    <lng>-76.812561</lng>
                </latLng>
                <latLng>
                    <lat>40.304954</lat>
                    <lng>-76.83039</lng>
                </latLng>
                <latLng>
                    <lat>40.304954</lat>
                    <lng>-76.83039</lng>
                </latLng>
                <latLng>
                    <lat>40.301498</lat>
                    <lng>-76.872665</lng>
                </latLng>
                <latLng>
                    <lat>40.301498</lat>
                    <lng>-76.872665</lng>
                </latLng>
                <latLng>
                    <lat>40.364498</lat>
                    <lng>-76.92881</lng>
                </latLng>
                <latLng>
                    <lat>40.368495</lat>
                    <lng>-76.981414</lng>
                </latLng>
                <latLng>
                    <lat>40.382682</lat>
                    <lng>-77.016967</lng>
                </latLng>
                <latLng>
                    <lat>40.397239</lat>
                    <lng>-77.008132</lng>
                </latLng>
                <latLng>
                    <lat>40.430889</lat>
                    <lng>-77.010658</lng>
                </latLng>
                <latLng>
                    <lat>40.471801</lat>
                    <lng>-77.032135</lng>
                </latLng>
                <latLng>
                    <lat>40.480957</lat>
                    <lng>-77.049224</lng>
                </latLng>
                <latLng>
                    <lat>40.479011</lat>
                    <lng>-77.068656</lng>
                </latLng>
                <latLng>
                    <lat>40.493789</lat>
                    <lng>-77.082611</lng>
                </latLng>
                <latLng>
                    <lat>40.498321</lat>
                    <lng>-77.126365</lng>
                </latLng>
                <latLng>
                    <lat>40.526847</lat>
                    <lng>-77.134216</lng>
                </latLng>
                <latLng>
                    <lat>40.564601</lat>
                    <lng>-77.169754</lng>
                </latLng>
                <latLng>
                    <lat>40.57061</lat>
                    <lng>-77.243759</lng>
                </latLng>
                <latLng>
                    <lat>40.539234</lat>
                    <lng>-77.341888</lng>
                </latLng>
                <latLng>
                    <lat>40.556442</lat>
                    <lng>-77.362098</lng>
                </latLng>
                <latLng>
                    <lat>40.594371</lat>
                    <lng>-77.377586</lng>
                </latLng>
                <latLng>
                    <lat>40.611503</lat>
                    <lng>-77.445732</lng>
                </latLng>
                <latLng>
                    <lat>40.579284</lat>
                    <lng>-77.551391</lng>
                </latLng>
                <latLng>
                    <lat>40.622348</lat>
                    <lng>-77.580848</lng>
                </latLng>
                <latLng>
                    <lat>40.653442</lat>
                    <lng>-77.583488</lng>
                </latLng>
                <latLng>
                    <lat>40.668922</lat>
                    <lng>-77.604171</lng>
                </latLng>
                <latLng>
                    <lat>40.683479</lat>
                    <lng>-77.607658</lng>
                </latLng>
                <latLng>
                    <lat>40.703529</lat>
                    <lng>-77.597267</lng>
                </latLng>
                <latLng>
                    <lat>40.727935</lat>
                    <lng>-77.604621</lng>
                </latLng>
                <latLng>
                    <lat>40.732955</lat>
                    <lng>-77.63565</lng>
                </latLng>
                <latLng>
                    <lat>40.760101</lat>
                    <lng>-77.614212</lng>
                </latLng>
                <latLng>
                    <lat>40.794662</lat>
                    <lng>-77.625228</lng>
                </latLng>
                <latLng>
                    <lat>40.798587</lat>
                    <lng>-77.656425</lng>
                </latLng>
                <latLng>
                    <lat>40.779037</lat>
                    <lng>-77.771057</lng>
                </latLng>
                <latLng>
                    <lat>40.779037</lat>
                    <lng>-77.771057</lng>
                </latLng>
                <latLng>
                    <lat>40.778633</lat>
                    <lng>-77.793205</lng>
                </latLng>
                <latLng>
                    <lat>40.778633</lat>
                    <lng>-77.793205</lng>
                </latLng>
                <latLng>
                    <lat>40.777702</lat>
                    <lng>-77.793266</lng>
                </latLng>
            </shapePoints>
            <legIndexes>
                <index>0</index>
                <index>56</index>
            </legIndexes>
            <maneuverIndexes>
                <index>0</index>
                <index>2</index>
                <index>4</index>
                <index>6</index>
                <index>8</index>
                <index>10</index>
                <index>12</index>
                <index>14</index>
                <index>16</index>
                <index>18</index>
                <index>20</index>
                <index>22</index>
                <index>52</index>
                <index>54</index>
                <index>55</index>
            </maneuverIndexes>
        </shape>
    </route>
</response>