Routing

Contents

Routing is done using Trimble MAPS data for commercial vehicles. 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.

Route #

The first step in adding routes to your map is to create a new Route object providing a RouteOptions object as a constructor parameter.

const myRoute = new TrimbleMaps.Route({
  //Put your RouteOptions attributes here
});

Route Options #

The RouteOptions object requires a routeId and an array of stops. There are a number of optional parameters that can also be provided in order to change the route path or the way it is displayed.

const myRoute = new TrimbleMaps.Route({
  routeId: "myRoute",
  stops: [
    new TrimbleMaps.LngLat(-74.566234, 40.49944),
    new TrimbleMaps.LngLat(-74.629749, 40.261187)
  ]
});

Adding the Route to a Map #

A route can be added to a map by calling the addTo method on the route object.

myMap.on('load', function() {
    myRoute.addTo(myMap);
});

Events #

A route will raise a series of events during the loading and rendering of the route. The primary events are the routeloading and route. The routeloading event is raised when the calls are started and the route event is raised when the route is completely loaded and rendered. These events can be useful for adding loading indicators to your application. The routeloading event could fire before start listening.

const myRoute = new TrimbleMaps.Route({
  routeId: "myRoute",
  stops: [
    new TrimbleMaps.LngLat(-74.566234, 40.49944),
    new TrimbleMaps.LngLat(-74.629749, 40.26118)
  ]
});

myRoute.on("routeloading", function () {
  console.log("loading route");
});

myRoute.on("route", function () {
  console.log("route complete");
});

Reports #

The requested reports for a route can be retrieved by listening to the report event on the route object. The report event will return an object containing all the reports specified in the reportType property in the route options. This event will be raised each time the route is updated. There is also a corresponding reportloading event that is raised when a report call is started.

const myRoute = new TrimbleMaps.Route({
  routeId: "myRoute",
  stops: [
    new TrimbleMaps.LngLat(-74.566234, 40.49944),
    new TrimbleMaps.LngLat(-74.629749, 40.26118)
  ],
  reportType: [
    TrimbleMaps.Common.ReportType.MILEAGE,
    TrimbleMaps.Common.ReportType.DETAIL
  ]
});

myRoute.on("report", function (reports) {
  console.log(reports);
});

Interactive Routes #

By default, routes are static. The route will be drawn on the map and the stops will be indicated by the appropriate icons. 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 option of the routing layer in the constructor to true.

const myRoute = new TrimbleMaps.Route({
    routeId: 'myRoute',
    stops: [
        new TrimbleMaps.LngLat(-74.566234, 40.499440),
        new TrimbleMaps.LngLat(-74.629749, 40.261187)
    ],
    isDraggable: true
})

Remove Route #

You can remove individual routes by calling the remove method. Route line and stop icons will be removed all together.

myRoute.remove();

Update Route #

After a route is added, it can be updated by calling the update method. This method can be used to update the number of stops for a route. It can also be used to update a limited selection of route display styles, including route color, stop image icons (preferably in .PNG format), icon size and icon offset. It can’t be used to change the text label, text offset, or text size.

myRoute.update({
    routeId: 'myRoute',
    routeColor: '#888'
});

Customize Route #

If more control over route stops styling is desired, instead of using the update method, construct a route with showStops set to false. You can then add custom stop icons using the addStopIcon method and style them using the styleStopIcons method.

const showDefaultStops = false; // If false, custom stop icons can be used, if other values, default icons and styles are used.
const myRoute = new TrimbleMaps.Route({
    routeId: 'myRoute',
    stops: [
        new TrimbleMaps.LngLat(-74.566234, 40.49944),
        new TrimbleMaps.LngLat(-74.528512, 40.386680),
        new TrimbleMaps.LngLat(-74.629749, 40.26118)
    ],
    showStops: showDefaultStops
});

myMap.on('load', function() {
    myRoute.addTo(myMap);
    if (!showDefaultStops) {
        // add custom stop icons.
        myRoute.addStopIcon('start', 'https://developer.trimblemaps.com/maps-sdk/img/marker_blue.png');
        myRoute.addStopIcon('end', 'https://developer.trimblemaps.com/maps-sdk/img/marker_blue.png');
        myRoute.addStopIcon('stop', 'https://developer.trimblemaps.com/maps-sdk/img/marker_blue.png');
        // style custom stop icons. For detailed information, visit https://developer.trimblemaps.com/maps-sdk/style-spec/layers/#symbol
        const stopLayerStyle = {
            layout: {
                'icon-size': [
                    'case',
                    ['==', ['get', 'stopType'], 'start'], 0.5, // stopType is an internal property, it has start, end, and stop values for now.
                    ['==', ['get', 'stopType'], 'end'], 0.5,
                    0.4 // stops
                ],
                'icon-offset': [0, -30]
            }
        };
        myRoute.styleStopIcons(stopLayerStyle);
    }
});
Last updated May 12, 2021.