Routing is done using ALK Maps Data. This data includes bridge heights and clearances, load limits, weight limits and allowances, one-way road designations, left-hand and dangerous turn restrictions, urban road classifications, as well as hazmat, truck-restricted, truck-designated and truck-prohibited roads.
The first step in generating routes is to add a routing layer to your map. The routing layer will be responsible for both retrieving and drawing the routes based on the stops and properties you define.
var routingLayer = new ALKMaps.Layer.Routing( "Route Layer" ); myMap.addLayer(routingLayer);
Once you have a routing layer added to your map, the next step is to add routes. To generate a route you will need at least two stops (an origin and a destination).
The addRoute method of the routing layer takes up to four parameters for creating a route: stops
, functionOptions
, routeOptions
, and reportOptions
.
The stops
parameter of the addRoute
method should contain an array of ALKMaps.LonLat
objects representing the stops of the route.
The functionOptions
parameter contains options related to the functionality of the route.
Parameter | Type | Description |
---|---|---|
routeId |
string |
A unique string values used to identify a route. It is needed when removing or updating a route. |
async |
boolean |
Default: true Determine whether the route request will be asynchronous. If so, a callback function can be specified. If a type of web browser, like IE, uses XDomainRequest to issue HTTP request, it is required to make asynchronous calls due to limitations of the browser. |
success |
function |
Function to be called on the success of the asynchronous routing request. The callback function will be passed a results object that contains the id , stops , and the reports .Function name "callback" has been deprecated. |
failure |
function |
Function to be called when error happens. |
style |
ALKMaps.StyleMap |
{strokeColor: "#00C000", strokeOpacity: 0.6} Currently, strokeOpacity and strokeColor are the supported styling options.
Note: See Route Colors for more information.
|
frameRoute |
boolean |
Default: true
Indicates whether the center point and zoom level of the map will be adjusted to show the route in full frame. |
showHandles |
boolean |
Default: true
Indicates whether to show the origin/waypoint/destination graphics. |
The routeOptions
parameter contains options related to the generation of the route and optional reports.
Parameter | Type/Values | Description |
---|---|---|
vehicleType |
[0 | 1 | 2] |
Default: 0 Restricts the route to roads that are accessible by the selected vehicle type.
|
routingType |
[0 | 1 | 2] |
Default: 0 Generated the route to match the type.
|
routeOptimization |
[0 | 1 | 2] |
Default: 0
|
tollDiscourage |
boolean |
Default: false Generates the route by trying to avoid toll roads. |
classOverrides |
[0 | 1 | 2] |
Default: 0
|
bordersOpen |
boolean |
Default: true Indicates whether borders are open for travel. |
overrideRestrict |
boolean |
Default: false
Indicates whether or not to override truck restrictions |
highwayOnly |
boolean |
Default: false Restricts the route to only highway roads. |
hazMatType |
[0 | 1 | 2 | 3 | 4 | 5 | 6 | 7] |
Default: 0
Restricts the route to roads that allow transportation of the selected hazardous material. See details in Glossary.
|
tunnelCategory |
[0 | 1 | 2 | 3 | 4] |
Default: 0
Indicates the tunnel categories which are applicable for EU region only.
|
sideOfStreetAdherence |
[0 | 1 | 2 | 3 | 4 | 5 | 6] |
Default: 0
How strict to be in order to avoid the destination being on the opposite side of the street.
|
governorSpeedLimit |
number |
Maximum average road speed to use in route calculations that overrides all other road speeds when they are above this value.
Default is disabled and valid value is between 1 and 100 mph or 1 and 161 kph based on distanceUnits .
|
distanceUnits |
[0 | 1] |
Default: 0
Distance units as miles or kilometers.
|
trkUnits |
[0 | 1] |
Default: 0
Vehicle dimension units; can be English or Metric.
|
trkHeight |
number |
The height of the vehicle in feet and inches or meters depending on units. Example 13'6" or 4.1148. |
trkLength |
number |
The length of the vehicle in feet and inches or meters depending on units. Example 13'6" or 4.1148. |
trkWidth |
number |
The width of the vehicle in feet and inches or meters depending on units. Example 13'6" or 4.1148. |
trkWeight |
number |
The weight of the vehicle in pounds or kilograms depending on units. |
trkAxles |
number |
Default: 5 The number of axles on the vehicle; acceptable values are 2 through 14. |
inclFerryDist |
boolean |
Default: true
Indicates whether or not to include ferry distances in mileage calculations. Note: This parameter is only used for Reports |
fuelUnits |
[0 | 1] |
Default: 0
Fuel units as gallons and liters.
|
truckConfig |
[0 | 1 | 2 | 3 | 4] |
Default: 0
The vehicle style.
|
inclTollData |
boolean |
Default: true
Indicates whether or not reports should calculate toll costs. Note: This parameter is only used for Reports |
fuelEconLoad |
number |
The fuel efficiency (distance units per fuel units) when loaded. Note: This parameter is only used for Reports |
fuelEconEmpty |
number |
The fuel efficiency (distance units per fuel units) when empty.
Note: This parameter is only used for Reports |
costPerFuelUnit |
number |
The cost per fuel unit of fuel.
Note: This parameter is only used for Reports |
costGHG |
number |
The cost of greenhouse gas in lbs. per fuel unit. Note: This parameter is only used for Reports |
costMaintLoad |
number |
The maintenance cost per distance unit when loaded.
Note: This parameter is only used for Reports |
costMaintEmpty |
number |
The maintenance cost per distance unit when empty. Note: This parameter is only used for Reports |
costTimeLoad |
number |
The time cost per mile/km when loaded. Note: This parameter is only used for Reports |
costTimeEmpty |
number |
The time cost per mile/km when empty. Note: This parameter is only used for Reports |
tollCurrency |
[0 | 1] |
Default: 0
The toll currency.
|
exchangeRate |
number |
The change rate to convert US dollars to Canadian dollars. Note: This parameter is only used for Reports |
tollPlan |
String |
The toll discount plan which is a comma-separated list of toll discount programs. Use All for everything otherwise valid values are (407ETR Transponder,A25 Transponder,BreezeBy,C-Pass,Cruise Card,E-Pass,E-Pass Canada,EXpress Toll,EZ Tag,EZPass,EZPass-NJ,EZPass-WV,FAST LANE,FasTrak,GeauxPass,Good To Go,GO-PASS,I-Pass,I-Zoom,K-TAG,Laredo Trade Tag,LeeWay,MACPASS,NC Quick Pass,NEXPress,Palmetto Pass,Peach Pass,PikePass,Quickpass,Smart Tag,StraitPASS,SunPass,TollTag,TxTag,Wabash Pass) |
citeInt |
number |
The cite interval to be used when generating a geotunnel report. The minimum value is 0.1. Note: This parameter is only used for Reports |
region |
[NA | EU | OC | SA |
Default: NA The data region in which the route stops are located. Note: If region is not provided, region value will be inherited from baseLayer region parameter. |
useSites |
Boolean |
Indicates whether to use sites as part of the route calculation.
If useSites is enabled and any of the stops on the route fall within an ALK site or applicable customer site,
then the route itself will be affected by those sites. Entry / exit gates to / from that stop will be added as part of the route.
Eventually the preferred first mile / last mile route path and reports will be affected.
Default: false Note: Site path will not be returned as part of route visualization. |
If you are a global highway customer that would like to use routing in another region, you can set dataset
to "Current"
inside of routeOptions
to use global highway data.
Parameter | Type/Values | Description |
---|---|---|
type |
[Mileage | Directions | Detail | State | |
Comma-separated list of requested report types. |
format |
[json | html] |
Default: json The format of the report returned with the route. |
dataVersion |
[Current | PCM_EU | PCM_OC | PCM_SA |
|
Default: current The data version against which this request should be performed. Note: Reports might be different from the route if older data version is used. |
lang |
[ENUS (English United States) |
|
Default: ENUS The language of the report returned with the route. |
condenseDirs |
Boolean |
Default: false Indicate whether or not to get the condensed version of the directions report. |
Please visit Route Reports and EU Toll Detail Report example pages and view the source code for more information.
You can remove individual routes in a particular routing layer by calling the removeRoute
method with the routeId
of the route you would like to remove.
routingLayer.removeRoute("myRoute");
By default, routes are static. The route will be drawn on the map and the stops will be indicated by the appropriate markers. If you would like to your users to interact with the routes by moving the location of stop or dragging the routes, you just need to set the isDraggable
property of the routing layer in the constructor to true
.
var routingLayer = new ALKMaps.Layer.Routing( "Route Layer", { isDraggable: true } ); myMap.addLayer(routingLayer);
The interactivity of a routing layer can also be set dynamically by calling the setDraggable
method on an existing routing layer.
routingLayer.setDraggable( false );
Once the user has moved around the stops, you may want to retrieve the new location of the stops, as well as any new stops that may have been created while dragging. The get this information you will need to use the getRouteElements
method on the routing layer. This method take the routeId
of the route.
var routeElements = routingLayer.getRouteElements("PhiladelphiaToAtlanticCity"); var numberOfStops = routeElements.stops.length; for (var i=0 ; i < numberOfStops ; i++){ console.log("Stop " + i); console.log("Lon: " + routeElements.stops[i].geometry.x); console.log("Lat: " + routeElements.stops[i].geometry.y); }
The route handles (icons displayed at the origin, destination, and waypoints) can be shown/hidden or changed.
The visibility of route handles can be set when the route is added via the showHandles
option in the functionOptions
of the addRoute
call.
routingLayer.addRoute({ ... functionOptions:{ routeId: "PhiladelphiaToAtlanticCity", showHandles: false }, ... });
The visibility can also be changed after the route has been created via a call to the setRouteHandleVisibility
on the routing layer. The function takes the routeId
and a boolean value indicating the visibility as parameters.
routingLayer.setRouteHandleVisibility("PhiladelphiaToAtlanticCity", false);
In addition to being hidden, the route handle graphics can be changed via the setRouteHandle
function on the routing layer. Changes to the route handle graphics only affect handles that are currently part of the route. Handles added after the graphic change will need to be set after they are added.
routingLayer.setRouteHandle( "MyRoute", "O", { externalGraphic: "https://maps.alk.com/api/1.2/img/fav.png" } );
The first parameter of setRouteHandle
is the routeId
of the route containing the handle to change.
The second parameter indicate which handle to change. This can be specified by either the type or index of the point. Valid types are "O" for origin, "D" for destination, or "W" for waypoint, or "A" for all types. If the route contains several stop/waypoints, all graphics will be updated. In addition to types, you may also specify the index to select the handle. The index is zero-based starting at the origin.
The third parameter is an object representing the style properties to be set. Valid style properties are:
Property | Description |
---|---|
externalGraphic |
The URL of the image to be used as the handle. |
graphicWidth |
The width of the image. |
graphicHeight |
The height of the image. |
graphicXOffset |
The X offset from the stop point. |
graphicYOffset |
The Y offset from the stop point. |
Different route colors are generated by the toolkit for each new route created. If you would like to specify a particular color for a route, you can pass in the color as a style object when the route is created.
routingLayer.addRoute({ ... functionOptions:{ routeId: "PhiladelphiaToAtlanticCity", style: { strokeOpacity: 0.9, strokeColor: "#0000FF" } }, ... });
Currently, strokeOpacity
, strokeColor
, strokeLinecap
, strokeWidth
and strokeDashstyle
are the supported styling options.
Stroke opacity value ranges are from 0 to 1. Stroke color takes hex code in string, like "#ee9900". Valid value for line cap is "butt", "round", or "square".
Valid value for dash style is "dot", "dash", "dashdot", "longdash", "longdashdot" or "solid" and most SLD patterns will render correctly.
If stroke width is supplied, default width in the context will be replaced.