Click or drag to resize

Telogis.GeoBase.Routing.Route

Verizon Connect Logo
Print this page
Learn more about Verizon Connect GeoBase.
Get information about the latest release
Route Class

A class for constructing point-to-point directions and optimizing multi-stop routes.

JavaScript
var LatLon = Telogis.GeoBase.LatLon;
var RouteStop = Telogis.GeoBase.Routing.RouteStop;

// Create three route stops
var RouteStop1 = new RouteStop(new LatLon(33.587512,-117.741400));
var RouteStop2 = new RouteStop(new LatLon(33.553872,-117.728464));
var RouteStop3 = new RouteStop(new LatLon(33.537614,-117.687859));

// Create an array of route stops
var StopsArray = [RouteStop1, RouteStop2, RouteStop3];

// Specify a routing strategy --  RoutingStrategyFastest is the default
var RoutingStrategyFastest = new Telogis.GeoBase.Routing.RoutingStrategyFastest();

// Create a new route
var myRoute = new Telogis.GeoBase.Routing.Route({
        stops: StopsArray,
        strategy: RoutingStrategyFastest
});

// Was the route created? Check that there are three stops...

// document.onclick = myTestFunction;
function myTestFunction() {
        alert ('There are ' + myRoute.getStopCount() + ' stops in this route.');
};
Constructor
NameDescription
Route(config)

Arguments

  • (Optional)config (Object) - Configuration options for the Routing.Route. Defaults to {}.

    Properties
    NameTypeDescription
    stopsArray

    The initial array of LatLon coordinate stops for the route to cover.

    Defaults to [].
    strategyRouting.RoutingStrategy

    A Routing.RoutingStrategy describing the constraints to use when calculating and optimizing the route.

    Defaults to new Routing.RoutingStrategyFastest ().
Functions
NameDescription
addStopAt (LatLon stop, Number index)

Adds a Routing.RouteStop to the route at a specified location in the list of stops.

JavaScript
var InsertStop = new Telogis.GeoBase.Routing.RouteStop(
    new Telogis.GeoBase.LatLon(33.587512,-117.741300));
// Add stop at list index 1
myRoute.addStopAt(InsertStop, 1);

// document.onclick = myTestFunction;
function myTestFunction() {
    alert ('Stop 1 in this route is now: ' + myRoute.getStop(1));
};
ArgumentsReturns

Routing.RouteStop - The RouteStop that was added to the route.

addWaypointAt (LatLon stop, Number index)

Adds a Routing.Waypoint to the route at a specified location in the list of stops.

JavaScript
var Waypoint = new Telogis.GeoBase.Routing.Waypoint(
    new Telogis.GeoBase.LatLon(33.587512,-117.741300)
);
// Add stop at route list index 2
myRoute.addWaypointAt(Waypoint, 2);
ArgumentsReturns

Routing.Waypoint - The Waypoint that was added to the route.

appendStop (LatLon stop)

Adds a Routing.RouteStop to the route, at the end of the ordered list of stops.

JavaScript
var NewRouteStop = new Telogis.GeoBase.Routing.RouteStop(
    new Telogis.GeoBase.LatLon(33.587512,-117.741400));
myRoute.appendStop(NewRouteStop);
ArgumentsReturns

Routing.RouteStop - The RouteStop that was added to the route.

appendStops (Array stops)

Adds all supplied Routing.RouteStops to the route at the end of the ordered list of stops.

JavaScript
// Create two new route stops
var newRS1 = new Telogis.GeoBase.Routing.RouteStop(new LatLon(33.612914,-117.745395));
var newRS2 = new Telogis.GeoBase.Routing.RouteStop(new LatLon(33.554736,-117.706501));

// Create an array using the stops
var NewStopsArray = [newRS1, newRS2];

// Append the array to the route
myRoute.appendStops(NewStopsArray);

// document.onclick = myTestFunction;
function myTestFunction() {
    alert ('There are now ' + myRoute.getStopCount() + ' stops in this route.');
};
Arguments
  • stops (Array) - An array of route stops to add, as LatLons.

Returns

Array - An array of Routing.RouteStops that were added to the route.

appendWaypoint (LatLon stop)

Adds a Routing.Waypoint to the route, at the end of the ordered list of stops.

JavaScript
var NewWaypoint = new Telogis.GeoBase.Routing.Waypoint(
    new Telogis.GeoBase.LatLon(33.587512,-117.741400));
myRoute.appendWaypoint(NewWaypoint);
ArgumentsReturns

Routing.Waypoint - The Waypoint that was added to the route.

getDirections (Function callback, Function errorCallback, String units, String culture, Object server)

Calculates the route and passes a representative Routing.Directions object to the specified callback.

JavaScript
var LatLon = Telogis.GeoBase.LatLon;
var RouteStop = Telogis.GeoBase.Routing.RouteStop;

// Create three route stops
var RouteStop1 = new RouteStop(new LatLon(33.587512,-117.741400));
var RouteStop2 = new RouteStop(new LatLon(33.553872,-117.728464));
var RouteStop3 = new RouteStop(new LatLon(33.537614,-117.687859));

// Create an array of route stops
var StopsArray = [RouteStop1, RouteStop2, RouteStop3];

// Specify a routing strategy --  RoutingStrategyFastest is the default
var RoutingStrategyFastest = new Telogis.GeoBase.Routing.RoutingStrategyFastest();

// Create a new route
var myRoute = new Telogis.GeoBase.Routing.Route({
    stops: StopsArray,
    strategy: RoutingStrategyFastest
});

// Specify the units and culture we will use for our Directions object
var units = 'Metric'; // Also accepts 'ImperialFeet' and 'ImperialYards'. Optional.
var culture = 'en-US'; // Optional.
var list = 'Direction instructions for this route:\n\n';

// Create a Directions object containing route navigation instructions
myRoute.getDirections(function (result) {
    var i;
    var count = 1;
        for (i = 0; i < result.getLength(); i++) {
                list +=  count + ': ' + result.getDirection(i).toString() + '\n' ;
                count++
        }
    }, function (error) {alert(error)}, units, culture
);

//document.onclick = myTestFunction;
function myTestFunction() {
        alert (list);
};
Arguments
  • callback (Function) - An arbitrary function to call when the directions have been fetched.

    Arguments
    • directions (Routing.Directions) - The resulting directions from the server-side call to GetDirectionsStateless.

  • (Optional) errorCallback (Function) - An arbitrary function, called only if an error or timeout occurs when fetching the directions. Returns the error or timeout that occurred. Defaults to null.

    Arguments
    • error (Telogis.Errors.GeoBaseError) - An exception describing the problem that was encountered.

  • units (String) - An optional argument describing the units that the directions are desired in. The valid unit strings can be found at Telogis.GeoBase.Navigation.UnitSystem. Valid units are 'Metric', 'ImperialFeet' or 'ImperialYards'.

  • culture (String) - An optional argument specifying the language of the directions to be fetched. Available cultures can be found by querying Telogis.GeoBase.getCultures().

  • server (Object) - An optional object that contains server.url (The address of the GeoStream server as a string) and server.authToken (The GeoStream authentication token to be used for requesting tiles) to be used for this request.

getEnd ()

Gets the location that the Routing.Routemust end at. If no end has been specified for the route, null is returned.

JavaScript
//... create a route (myRoute) without a specified end location, then:
//document.onclick = myTestFunction; // test trigger
function myTestFunction() {
        // No end defined so returns 'null'
        alert ('The end of this route (undefined end) is ' + myRoute.getEnd());
        // Now specify a route stop, which is returned
        myRoute.setEnd(RouteStop1);
        alert ('The end of this route is now ' + myRoute.getEnd());
};
Returns

LatLon - The location that the route ends at.

getPath (Function callback, Function errorCallback, Object server)

Calculates the route and passes a representative Routing.Directions object without textual driving instructions to the specified callback.

JavaScript
// Create a route ('myRoute') and a map object ('map') then..
myRoute.getPath(function (result) {
    dirsLayer = new Telogis.GeoBase.MapLayers.RouteLayer({
        id: 'route_directions',
        map: map,
        lineColor: new Telogis.GeoBase.Color(0,18,255, 0.5),
        lineWidth: 6
    });
    dirsLayer.setPoints(result.getPoints());
    dirsLayer.show();
    }, function (error) {alert(error)}
);
Arguments
  • callback (Function) - An arbitrary function to call when the directions have been fetched.

    Arguments
    • directions (Routing.Directions) - The resulting directions from the server-side call to GetPath.

  • (Optional) errorCallback (Function) - An arbitrary function, called only if an error or timeout occurs when fetching the directions. Returns the error or timeout that occurred. Defaults to null.

    Arguments
    • error (Telogis.Errors.GeoBaseError) - An exception describing the problem that was encountered.

  • server (Object) - An optional object that contains server.url (The address of the GeoStream server as a string) and server.authToken (The GeoStream authentication token to be used for requesting tiles) to be used for this request.

getQuickDirections (Function callback, Function errorCallback, Object server)

Get the 'quick directions', ignoring legality and without generating natural language directions.

JavaScript
// Create a route ('myRoute') and a map object ('map') then..
myRoute.getQuickDirections(function (result) {
    dirsLayer = new Telogis.GeoBase.MapLayers.RouteLayer({
        id: 'route_directions',
        map: map,
        lineColor: new Telogis.GeoBase.Color(0,18,255, 0.5),
        lineWidth: 6
    });
    dirsLayer.setPoints(result.getPoints());
    dirsLayer.show();
    }, function (error) {alert(error)}
);
Arguments
  • callback (Function) - The function to call when the directions have been fetched.

    Arguments
    • directions (Routing.Directions) - The resulting directions from the server-side call to GetQuickDirectionsStateless.

  • (Optional) errorCallback (Function) - An arbitrary function, called only if an error or timeout occurs when fetching the directions. Defaults to null.

    Arguments
    • error (Telogis.Errors.GeoBaseError) - An exception describing the problem that was encountered.

  • server (Object) - An optional object that contains server.url (The address of the GeoStream server as a string) and server.authToken (The GeoStream authentication token to be used for requesting tiles) to be used for this request.

getRouteHighlight (Function callback, Function errorCallback, String dataUrl, Object server, Array customRoutingAccessKeys)

Reads point data from a file, gets the likely route that was taken between the points, and passes an abbreviated Routing.Directions object to the specified callback.

JavaScript
// Create a map object (map), then...
// Create a route object
var myRoute = new Telogis.GeoBase.Routing.Route();
dir = myRoute.getRouteHighlight(
    // Callback function 
    function(result){
        // Create a map layer to display the route highlight on
        dirsLayer = new Telogis.GeoBase.MapLayers.RouteLayer({
            id: 'route_highlight',
            map: map
        });
        // Add the fetched directions to the map layer
        dirsLayer.setPoints(result.getPoints());
        dirsLayer.show();
    },
    // Error function
    function(error){
        alert(error);
    },
    // URL of CSV data file
    'http://localhost/GeoStream/highlight.csv'
);
Arguments
  • callback (Function) - An arbitrary function to call when the directions have been fetched.

    Arguments
    • directions (Routing.Directions) - The resulting directions from the server-side call to GetRouteHighlightStateless.

  • (Optional) errorCallback (Function) - An arbitrary callback to execute if an error or timeout occurs when fetching directions. Defaults to null.

    Arguments
    • error (Telogis.Errors.GeoBaseError) - An exception describing the problem that was encountered.

  • dataUrl (String) - URL of the CSV file on the server that contains the route stop data. The first row of the file must contain only the column heading StartTime, followed on the second row by the start time, in ticks since the epoch. In the third row, the following column headings are required: Lat, Lon, TimeSincePreviousStop. Heading and Speed columns are optional. Columns can appear in any order, and GeoStream will ignore any columns it doesn't recognize.

  • server (Object) - An optional object that contains server.url and server.authToken to be used for this request

  • customRoutingAccessKeys (Array) - An optional array of custom routing access key strings

getStart ()

Gets the location that the Routing.Routemust begin at. If no start has been specified for the route, null is returned.

JavaScript
//... create a route (myRoute) without a specified start location, then:
//document.onclick = myTestFunction; // test trigger
function myTestFunction() {
        // No end defined so returns 'null'
        alert ('The start of this route (undefined start) is ' + myRoute.getStart());
        // Now specify a route stop, which is returned
        myRoute.setStart(RouteStop1);
        alert ('The start of this route is now ' + myRoute.getStart());
};
Returns

LatLon - The location that the route starts at.

getStop (Number i)

Finds the stop at a given placing in the route.

JavaScript
//... create a route (myRoute) with at least three stops, then:
//document.onclick = myTestFunction; // test trigger
function myTestFunction() {
        // zero-based: first stop is '0', third stop '2'
        alert ('The first stop in this route is ' + myRoute.getStop(0) +
        ' the third stop is ' +  myRoute.getStop(2));
};
Arguments
  • i (Number) - The index of the stop to get.

Returns

LatLon - The stop at position Routing.Route.getStop.i in the route.

getStopCount ()

Finds how many stops there are in the route.

JavaScript
//... create a route (myRoute), then:
//document.onclick = myTestFunction; // test trigger
function myTestFunction() {
        alert ('Stops in this route: ' + myRoute.getStopCount());
};
Returns

Number - The number of stops that the route is comprised of.

getVehicleSpec ()

Gets the specification used to ensure the route is safe for this vehicle.

JavaScript
// ... create a route (myRoute) and
// apply a vehiclespec, then:
var mySpec = myRoute.getVehicleSpec();
Returns

Routing.VehicleSpec - The Routing.VehicleSpec to be used for this route.

optimize (Function callback, Function errorCallback, Object server)

Rearranges the route's stops for maximum efficiency by the current routing strategy. While a callback function is triggered, the results of the optimization call (a differently-ordered array of stops) are automatically used to modify the route, so no parameters are passed to it.

JavaScript
//... create a route (myRoute), then:

var count = 1;
var before_list = 'pre-optimization route order:\n\n';
var after_list = 'post-optimization route order:\n\n';

for (x = 0; x < myRoute.getStopCount(); x++) {
    before_list += count + ': ' + myRoute.getStop(x) + '\n';
    count++;
}

// Write out the route stops
alert (before_list);

// Optimize the route
myRoute.optimize(function(){
        alert ('Route optimized...');
    }, function (error) {alert(error)}
);

////
//// NOTE: The optimization process may take several seconds to
//// complete, depending on the size and complexity of the route
////

// Once the route has been optimized (wait required) the route can be re-queried
count = 1;
for (y = 0; y < myRoute.getStopCount(); y++) {
    after_list += count + ': ' + myRoute.getStop(y) + '\n';
}

// Write out the route stops again
alert (after_list);
Arguments
  • (Optional) callback (Function) - An arbitrary function to call when the optimizations have been fetched. Defaults to null.

  • (Optional) errorCallback (Function) - An arbitrary callback to execute if an error or timeout occurs when optimizing the route. Defaults to null.

    Arguments
    • error (Telogis.Errors.GeoBaseError) - An exception describing the problem that was encountered.

  • server (Object) - An optional object that contains server.url (The address of the GeoStream server as a string) and server.authToken (The GeoStream authentication token to be used for requesting tiles) to be used for this request.

removeStopAt (Number index)

Removes the stop at the specified index from the route.

Arguments
  • index (Number) - The index to remove the RouteStop from.

setCustomRoutingAccessKeys (Array customRoutingAccessKeys)

Sets the custom routing access keys, which determine which roads can be routed on.

Arguments
  • customRoutingAccessKeys (Array) - An array of custom routing access key strings.

setEnd (LatLon stop)

Specifies a location that the Routing.Routemust end at. This stop is not displaced during optimization. If an end was already specified for the route, it is overridden.

JavaScript
//... create a route (myRoute), then:
var myEnd = new Telogis.GeoBase.Routing.RouteStop(new Telogis.GeoBase.LatLon(33.572158,-117.721639));
myRoute.setEnd(myEnd);
Arguments
setStart (LatLon stop)

Specifies a location that the Routing.Routemust begin at. This stop is not displaced during optimization. If a start was already specified for the route, it is overridden.

JavaScript
//... create a route (myRoute), then:
var myStart = new Telogis.GeoBase.Routing.RouteStop(new Telogis.GeoBase.LatLon(33.572158,-117.721639));
myRoute.setStart(myStart);
Arguments
setStrategy (Routing.RoutingStrategy strategy)

Sets the technique used to optimize the route.

JavaScript
//... create a route (myRoute), then:
var RoutingStrategyShortest = new Telogis.GeoBase.Routing.RoutingStrategyShortest();
myRoute.setStrategy(RoutingStrategyShortest);
Arguments
setVehicleSpec (Routing.VehicleSpec vehicleSpec)

Sets the specification used to ensure the route is safe for this vehicle.

JavaScript
// ... create a route (myRoute), then:

// Create a new vehicle specifications object
var VehSpec = new Telogis.GeoBase.Routing.VehicleSpec();

// Set the vehicle type (tractor semi trailer)
VehSpec.VehicleType = Telogis.GeoBase.Routing.VehicleType.TractorSemiTrailer;

// Apply the VehicleSpec to a route --
// Routes will now be generated that are legal for the vehicle specified
myRoute.setVehicleSpec(VehSpec);
Arguments
useTraffic (Object trafficConfig)

Specifies traffic parameters to be used when calculating and optimizing the Routing.Route. The supplied configuration will replace the existing traffic configuration.

JavaScript
route.useTraffic({});
route.useTraffic({source: "LosAngeles"});
route.useTraffic({source: "LosAngeles", time: new Date()});
route.useTraffic({source: "LosAngeles", time: "01-Jan-2013 12:00:00"});
Arguments
  • trafficConfig (Object) - Traffic configurations have "source" property of type String, and a "time" property of type Date or String.

    Properties
    NameTypeDescription
    sourceString

    The source of the traffic as a string, for example "LosAngeles". If no value is specified, no traffic is used.

    timeString

    A date or string specifying the traffic time to use when optimizing routes, for example "01-Jan-2013 12:00:00". If no time is specified, the current system time will be used.