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:
sessionId
attribute.
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.
http://www.mapquestapi.com/directions/v2/routeshape
| Response Formats | JSON, XML |
|---|---|
| Authentication | Yes (Requires Key) |
| Rate Limited | Yes |
| 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:
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:
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.
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 |
| 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. |
GET
http://www.mapquestapi.com/directions/v2/routeshape?key=KEY&sessionId=SESSION_ID&mapWidth=320&mapHeight=240&mapScale=1733371&mapLat=40.491304&mapLng=-77.2614665
{
"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": "© 2018 MapQuest, Inc.",
"imageUrl": "http://api.mqcdn.com/res/mqlogo.gif",
"imageAltText": "© 2018 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>© 2018 MapQuest, Inc.</imageAltText>
<text>© 2018 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>