Skip to content

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

https://www.mapquestapi.com/directions/v2/routeshape

Resource Information

Response FormatsJSON, XML
AuthenticationYes (Requires Key)
Rate LimitedYes

Request Parameters

Request ParameterDescriptionRequired
key
String
The API Key, which is needed to make requests to MapQuest services.Yes
sessionIdThe sessionId associated with the base route upon which you want to base your request.Yes
fullShapeReturns 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 generalize options
Default: false
Yes, unless mapState is specified.
generalizeIf 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
outFormatSpecifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
Default: json
No
callbackA 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

mapState required, unless fullShape is specified.

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
  • mapLngmapLat and mapLng represent the latitude and longitude of the center of the map.

Response

Response FieldDescription
shapeA 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.
legIndexesReturns 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.
maneuverIndexesReturns an array of the starting index for each maneuver.
shapePointsShape 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.
boundingBoxReturns 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
optionsReturns route options for the route specified by the sessionId
infoThis 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 https://www.mapquestapi.com/directions/v2/routeshape?key=KEY&sessionId=SESSION_ID&mapWidth=320&mapHeight=240&mapScale=1733371&mapLat=40.491304&mapLng=-77.2614665

Example Response

JSON
{
  "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": "© 2023 MapQuest, Inc.",
      "imageUrl": "https://api.mqcdn.com/res/mqlogo.gif",
      "imageAltText": "© 2023 MapQuest, Inc."
    },
    "statuscode": 0,
    "messages": []
  }
}
XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <info>
        <statusCode>0</statusCode>
        <messages/>
        <copyright>
            <imageUrl>https://api.mqcdn.com/res/mqlogo.gif</imageUrl>
            <imageAltText>© 2023 MapQuest, Inc.</imageAltText>
            <text>© 2023 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>