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:
- Send a normal Route request. The RouteResponse from this request will include a
sessionIdattribute. - Send a Route Shape request, and include the
sessionIdreturned 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
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 |
| fullShape | Returns all shapes (no generalization or clipping). This option overrides any mapState or generalize options.
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 | 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 |
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
mapZoomis provided, it will override the value ofmapScale. See Zoom to Scale Mapping for information on scales versus zoom levels. - mapLat
- mapLng
mapLatandmapLngrepresent the latitude and longitude of the center of the map.
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 | 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.
|
| 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
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>