Routing

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 TrimbleMaps.Route object.

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.

myRoute.addTo(myMap);

Route Options

ParameterTypeDescription
routeId
string
A unique string values used to identify a route.
stops
Array
An array of at least two TrimbleMaps.LngLat objects containing the locations of the stops of the route.
vehicleType
enumeration
Default: TrimbleMaps.Common.VehicleType.TRUCK
Restricts the route to roads that are accessible by the selected vehicle type.
  • TrimbleMaps.Common.VehicleType.TRUCK - Truck
  • TrimbleMaps.Common.VehicleType.LIGHT_TRUCK - Light Truck
  • TrimbleMaps.Common.VehicleType.AUTOMOBILE - Automobile
routeType
enumeration
Default: TrimbleMaps.Common.RouteType.PRACTICAL
Type of route.
  • TrimbleMaps.Common.RouteType.PRACTICAL - Practical
  • TrimbleMaps.Common.RouteType.SHORTEST - Shortest
  • TrimbleMaps.Common.RouteType.FASTEST - Fastest
routeOptimization
enumeration
Default: TrimbleMaps.Common.RouteOptimization.NONE
  • TrimbleMaps.Common.RouteOptimization.NONE - None
  • TrimbleMaps.Common.RouteOptimization.OPTIMIZE_ALL_STOPS - Optimize all stops
  • TrimbleMaps.Common.RouteOptimization.OPTIMIZE_INTERMEDIATE_STOPS - Optimize intermediate stops
tollDiscourage
boolean
Default: false
Generates the route by trying to avoid toll roads.
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
enumeration
Default: TrimbleMaps.Common.HazMatType.NONE
Restricts the route to roads that allow transportation of the selected hazardous material.
  • TrimbleMaps.Common.HazMatType.NONE - None
  • TrimbleMaps.Common.HazMatType.GENERAL - General
  • TrimbleMaps.Common.HazMatType.CAUSTIC - Caustic
  • TrimbleMaps.Common.HazMatType.EXPLOSIVES - Explosives
  • TrimbleMaps.Common.HazMatType.FLAMMABLE - Flammable
  • TrimbleMaps.Common.HazMatType.INHALANTS - Inhalants
  • TrimbleMaps.Common.HazMatType.RADIOACTIVE - Radioactive
distanceUnits
enumeration
Default: TrimbleMaps.Common.DistanceUnit.MILES
Distance units as miles or kilometers.
  • TrimbleMaps.Common.DistanceUnit.MILES - Miles
  • TrimbleMaps.Common.DistanceUnit.KILOMETERS - Kilometers
trkUnits
enumeration
Default: TrimbleMaps.Common.TruckUnit.ENGLISH
Distance units as miles or kilometers.
  • TrimbleMaps.Common.TruckUnit.ENGLISH - English
  • TrimbleMaps.Common.TruckUnit.METRIC - 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 of reports.
fuelUnits
enumeration
Default: TrimbleMaps.Common.FuelUnit.GALLONS
Fuel units as gallons and liters.
  • TrimbleMaps.Common.FuelUnit.GALLONS - Gallons
  • TrimbleMaps.Common.FuelUnit.LITERS - Liters
truckConfig
enumeration
Default: TrimbleMaps.Common.TruckConfig.NONE
The vehicle style.
  • TrimbleMaps.Common.TruckConfig.NONE - Indicates that no particular vehicle style is chosen.
  • TrimbleMaps.Common.TruckConfig.TWENTY_EIGHT - 28' double trailer.
  • TrimbleMaps.Common.TruckConfig.FORTY - 40' straight trailer.
  • TrimbleMaps.Common.TruckConfig.FORTY_EIGHT - 48' semitrailer.
  • TrimbleMaps.Common.TruckConfig.FIFTY_THREE - 53' semitrailer.
inclTollData
boolean
Default: true
Indicates whether or not reports should calculate toll costs in reports.
fuelEconLoad
number
The fuel efficiency (distance units per fuel units) when loaded. Used for reports.
fuelEconEmpty
number
The fuel efficiency (distance units per fuel units) when empty. Used for reports.
costPerFuelUnit
number
The cost per fuel unit of fuel. Used for reports.
costGHG
number
The cost of greenhouse gas in lbs. per fuel unit. Used for reports.
costMaintLoad
number
The maintenance cost per distance unit when loaded. Used for reports.
costMaintEmpty
number
The maintenance cost per distance unit when empty. Used for reports.
costTimeLoad
number
The time cost per mile/km when loaded. Used for reports.
costTimeEmpty
number
The time cost per mile/km when empty. Used for reports.
tollCurrency
enumeration
Default: TrimbleMaps.Common.TollCurrency.USD
The toll currency.
  • TrimbleMaps.Common.TollCurrency.USD - Indicates that the currency should be United States dollars.
  • TrimbleMaps.Common.TollCurrency.CAD - Indicates that the currency should be Canadian dollars.
exchangeRate
number
The change rate to convert US dollars to Canadian dollars. Used for reports.
citeInt
number
The cite interval to be used when generating a geotunnel report. The minimum value is 0.1. Used for reports.
region
enumeration
Default: TrimbleMaps.Common.Region.NA
The data region in which the route stops are located.
  • TrimbleMaps.Common.Region.AF - Africa
  • TrimbleMaps.Common.Region.AS - Asia
  • TrimbleMaps.Common.Region.EU - Europe
  • TrimbleMaps.Common.Region.ME - Middle East
  • TrimbleMaps.Common.Region.NA - North America
  • TrimbleMaps.Common.Region.OC - Australia
  • TrimbleMaps.Common.Region.SA - South America
  • TrimbleMaps.Common.Region.WW - Worldwide
reportType
Array
Default: [TrimbleMaps.Common.ReportType.MILEAGE]
The data region in which the route stops are located.
  • TrimbleMaps.Common.ReportType.MILEAGE - Mileage
  • TrimbleMaps.Common.ReportType.DIRECTIONS - Directions
  • TrimbleMaps.Common.ReportType.DETAIL - Detail
  • TrimbleMaps.Common.ReportType.STATE - State
  • TrimbleMaps.Common.ReportType.TOLL - Toll Detail

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 you application.

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);
});