Class GSRoute

GSRoute is the main class for calculating routes between geographic locations.

Requires: routing, svg modules

Class Summary
Constructor Attributes	Constructor Name and Description
	GSRoute(options) Creates a new `GSRoute` object that is initialized with the properties provided in the `options` object literal.

Method Summary
Method Attributes	Method Name and Description
	addListener(obj) Adds the specified object as a listener on this object.
	addWaypoint(waypoint) Adds a waypoint at the end of this route.
	calculate(onSuccess, onFailure) Calculate the route path lines and driving instructions for the current set of waypoints.
	canDragToInsertWaypoints() Returns the value of the `dragToInsertWaypoints` options
	clear() Removes all existing route data and waypoints from the route object.
	formatDistance(distance) Creates a textual representation of a distance.
	formatTime(time) Creates a textual representation of a duration e.g.
	getBounds() Get the bounds of the route path
	getDistance() Get the total distance for all legs in the route.
	getInstructionDistanceDecimalPlaces() Returns the value of the `instructionDistanceDecimalPlaces` option
	getLegs() Get the legs that have been calculated for the route.
	getStyle() Returns the style configuration for this route
	getTime() Get the total time for all legs in the route.
	getWaypointByIndex(index) Get a waypoint by index
	getWaypointCount() Get the total number of waypoints in the route
	getWaypointIndex(waypoint) Get the index for a specified waypoint
	insertWaypointAfter(waypoint, referenceWaypoint) Inserts the specified waypoint after a reference waypoint in the list of waypoints maintained by this route.
	insertWaypointBefore(waypoint, referenceWaypoint) Inserts the specified waypoint before a reference waypoint in the list of waypoints maintained by this route.
	removeListener(obj) Removes the specified object as a listener from this object
	removeWaypoint(waypoint) Removes a specified waypoint from the route
	replaceWaypoint(waypoint, referenceWaypoint) Replaces the specified waypoint after a reference waypoint in the list of waypoints maintained by this route.
	replaceWaypointAtIndex(waypoint, index) Replaces (or sets) a waypoint at a specific index
	setData(data, waypointLabels) Set the path/instruction data for the route manually.
	toGeoJsonObj() Outputs a GeoJSON object representation of this route's waypoints

Event Summary
Event Attributes	Event Name and Description
	routeCalculated(route)
	routeCalculating(route)
	routeCalculationFailed(route, errorCode, waypoints)

Class Detail

GSRoute(options)

Creates a new GSRoute object that is initialized with the properties provided in the options object literal.

The sample code below creates a new GSRoute object and adds two waypoints to the route. The route is then calculated and automatically added to the layer (specified via the options):

For further information see: Routing with Maps API v3.

var route = new GSRoute({
    directionsServiceUrl: 'http://directions/service/url',
    layer: map.createLayer('route')
});
route.addWaypoint(new GSWaypoint(new GSPoint(2665166, 6493817), {label: 'GeoSmart'}));
route.addWaypoint(new GSWaypoint(new GSPoint(2667978, 6482674), {label: 'Queen Street'));
route.calculate();

Parameters:

{Object} options Optional

an object literal specifying options for this route. The following options may be specified:

{String} options.directionsServiceUrl

the directions service URL. Typically this will refer to a web proxy to avoid disclosing authentication credentials (see here)

{boolean} options.returnToStart

if true the calculated route will return to the origin waypoint

{boolean} options.calculateInstructions

if false driving instructions will not be calculated

{boolean} options.dragToInsertWaypoints

if true the user will be able to drag off the route path to insert waypoints (waypoint type will be via)

{Array} options.waypoints

an array of GSWaypoint objects defining the route

{String} options.distanceUnit.

The unit to use for distances. Can be "Km" or "m". Defaults to "Km"

{Object} options.style

see GSPolyline style options

{Object} options.instructionTemplates

an object literal containing the text templates for the instructions output. Defaults are:

var templates = {
  start: 'Starting from <strong>[waypoint]</strong>, go <strong>[bearing]</strong> on <strong>[roadname]</strong>',
  stop: 'Continue for [distance] ' + distanceUnit + ' along <strong>[roadname]</strong> to <strong>[waypoint]</strong>',
  roundabout: 'After [distance] ' + distanceUnit + ' go <strong>[direction]</strong> ' + 
              'at the roundabout onto <strong>[roadname]</strong>',
  turn: 'After [distance] ' + distanceUnit + ' go <strong>[direction]</strong> onto <strong>[roadname]</strong>',
  uturn: 'Make a <strong>U-turn</strong>',
  nodistanceturn: 'Go <strong>[direction]</strong> onto <strong>[roadname]</strong>',
  fly: 'Fly [distance] ' + distanceUnit + ' to <strong>[roadname]</strong>'
};

Method Detail

{boolean} addListener(obj)

Adds the specified object as a listener on this object. The listener object should provide callback methods for any events it wishes to support

Parameters:
{Object} obj: the object that should be added as a listener

Returns:: {boolean} true if the object was successfully added as a listener

{GSWaypoint} addWaypoint(waypoint)

Adds a waypoint at the end of this route.

Parameters:
{GSWaypoint} waypoint: the waypoint to add

Returns:: {GSWaypoint} the waypoint that was added

calculate(onSuccess, onFailure)

Calculate the route path lines and driving instructions for the current set of waypoints. If a layer has been defined for the route then the route line will be automatically added to that layer after the route has been calculated

Parameters:
{function} onSuccess: a function that will be called after successfully calculating the route
{function} onFailure: a function that will be called if the route could not be calculated

Throws:
{Error}: if the number of waypoints < 2

{boolean} canDragToInsertWaypoints()

Returns the value of the dragToInsertWaypoints options

Returns:: {boolean} true if the route can be dragged to insert waypoints

clear()

Removes all existing route data and waypoints from the route object. Also removes the route path lines from the map

{String} formatDistance(distance)

Creates a textual representation of a distance. Distances under 100 Km will be returned with one decimal place of precision. Distances over 100 Km have no decimal places. e.g. for input distance 35600, the output would be "35.6 Km", for input distance 125400, the output would be "125 Km"

var distance = route.formatDistance(route.getDistance());

Parameters:
{int} distance: the distance in metres

Returns:: {String} the textual representation of the distance

{String} formatTime(time)

Creates a textual representation of a duration e.g. for input time 190.24, the output would be "3 hours 10 mins"

var time = route.formatTime(route.getTime());

Parameters:
{float} time: the time in minutes

Returns:: {String} a textual representation of the duration

{GSBounds} getBounds()

Get the bounds of the route path

Returns:: {GSBounds} the bounds of the route path

{int} getDistance()

Get the total distance for all legs in the route. Only available after the route has been calculated (see #calculate)

Returns:: {int} the total distance for all legs (in metres}

See:: GSRoute#formatDistance

{int} getInstructionDistanceDecimalPlaces()

Returns the value of the instructionDistanceDecimalPlaces option

Returns:: {int} the value of the instructionDistanceDecimalPlaces

{GSRouteLeg[]} getLegs()

Get the legs that have been calculated for the route. Only available after the route has been calculated (see GSRoute#calculate)

Returns:: {GSRouteLeg[]} an array of GSRouteLeg objects

{Object} getStyle()

Returns the style configuration for this route

Returns:: {Object} the style configuration

{float} getTime()

Get the total time for all legs in the route. Only available after the route has been calculated (see #calculate)

Returns:: {float} the total time for all legs (in minutes)

See:: GSRoute#formatTime

{GSWaypoint} getWaypointByIndex(index)

Get a waypoint by index

Parameters:
{int} index: the index of the waypoint to return

Returns:: {GSWaypoint} the way point at the specified index

{int} getWaypointCount()

Get the total number of waypoints in the route

Returns:: {int} a count of the total number of waypoints in the route

{int} getWaypointIndex(waypoint)

Get the index for a specified waypoint

Parameters:
{GSWaypoint} waypoint: the waypoint to get the index for

Returns:: {int} the index of the waypoint, or false if not found

insertWaypointAfter(waypoint, referenceWaypoint)

Inserts the specified waypoint after a reference waypoint in the list of waypoints maintained by this route. If referenceWaypoint is null, or not found, the waypoint is inserted at the end of the list of waypoints

Parameters:
{GSWaypoint} waypoint: the waypoint to insert
{GSWaypoint} referenceWaypoint: the waypoint to insert new waypoint after

See:: GSRoute#insertWaypointBefore

insertWaypointBefore(waypoint, referenceWaypoint)

Inserts the specified waypoint before a reference waypoint in the list of waypoints maintained by this route. If referenceWaypoint is null, or not found, the waypoint is inserted at the end of the list of waypoints

Parameters:
{GSWaypoint} waypoint: the waypoint to insert
{GSWaypoint} referenceWaypoint: the waypoint to insert the new waypoint before

See:: GSRoute#insertWaypointAfter

{boolean} removeListener(obj)

Removes the specified object as a listener from this object

Parameters:
{Object} obj: the object that should be removed as a listener

Returns:: {boolean} true if the specified listener object was removed successfully

{boolean} removeWaypoint(waypoint)

Removes a specified waypoint from the route

Parameters:
{GSWaypoint} waypoint: the waypoint to remove

Returns:: {boolean} returns true if the point was successfully removed, or false if it could not be found

replaceWaypoint(waypoint, referenceWaypoint)

Replaces the specified waypoint after a reference waypoint in the list of waypoints maintained by this route. If referenceWaypoint is null, or not found, the waypoint is inserted at the end of the list of waypoints

Parameters:
{GSWaypoint} waypoint: the waypoint to add
{GSWaypoint} referenceWaypoint: the waypoint to be replaced

See:: GSRoute#insertWaypointBefore; GSRoute#insertWaypointAfter

{GSWaypoint} replaceWaypointAtIndex(waypoint, index)

Replaces (or sets) a waypoint at a specific index

Parameters:
{GSWaypoint} waypoint: the new waypoint
{int} index: the index to replace the waypoint re

Returns:: {GSWaypoint} the waypoint that was set

setData(data, waypointLabels)

Set the path/instruction data for the route manually. This data can be obtained by querying the Navigator web service directly

Parameters:
{Object} data: the path/instruction data returned from the Navigator web service
{String[]} waypointLabels: an array of labels for the waypoints in the route. Required to build driving instructions

{Object} toGeoJsonObj()

Outputs a GeoJSON object representation of this route's waypoints

Returns:: {Object} a GeoJSON object

Event Detail

routeCalculated(route)

Parameters:
{GSRoute} route: a reference to the route that was calculated

routeCalculating(route)

Parameters:
{GSRoute} route: a reference to the route being calculated

routeCalculationFailed(route, errorCode, waypoints)

Parameters:
{GSRoute} route: a reference to the route that was being calculated
{String} errorCode: an error code indicating the reason the calculation failed
{Array} waypoints Optional: if the route calculation failed due to a snapping error an array of the waypoints which failed to be snapped will be returned