JavaScript Maps SDK

Route

Contents

Creates a route component

Param

RouteOptions

Parameter Type Description
options.routeId string A unique string value used to identify a route. It is needed when removing or updating a route.
options.routeColor string The color of the route line
options.routePathOpacity number The opacity of the route line
options.routeWidth RouteWidth | number The width of the route line. Example 20 or {stops: [[10, 7],[15, 9],[19, 11]]}
options.stops Array<LngLatLike | StopOptions> An array of at least two TrimbleMaps.LngLat or StopOptions objects containing the locations of the stops of the route. When StopOptions are used, the requestMethod parameter will be ignored and the type will be POST.
options.vehicleType Common.VehicleType Default: TrimbleMaps.Common.VehicleType.TRUCK
Restricts the route to roads that are accessible by the selected vehicle type.
options.routeType Common.RouteType Default: TrimbleMaps.Common.RouteType.PRACTICAL
Type of route.
options.routeOptimization Common.RouteOptimization Default: TrimbleMaps.Common.RouteOptimization.NONE
Route optimization type.
options.tollDiscourage boolean Default: false
Generates the route by trying to avoid toll roads. Deprecated.
options.tollRoads Common.TollRoadsType Default is null. If it is null, tollDiscourage will be used.
options.afSetIDs Array<number> The IDs of the Route Modifier (avoid/favor) sets that should be applied to the route. Set to [-1] to select all sets.
options.afSetNames Array<string> The names of the Route Modifier (avoid/favor) sets that should be applied to the route. Default is an empty set.
options.bordersOpen boolean Default: true
Indicates whether borders are open for travel.
options.overrideRestrict boolean Default: false
Indicates whether or not to override truck restrictions.
options.highwayOnly boolean Default: false
Restricts the route to only highway roads.
options.hazMatType Common.HazMatType Default: TrimbleMaps.Common.HazMatType.NONE
Restricts the route to roads that allow transportation of the selected hazardous material. Deprecated. Use hazMatTypes instead.
options.hazMatTypes Array<Common.HazMatType> Indicates the hazardous material types.
options.tunnelCategories Array<Common.TunnelCategory> Represents the EU Tunnel categories.
options.customRoadSpeeds Array<RoadSpeedBase> A list of custom road speeds to be applied for the route.
options.distanceUnits Common.DistanceUnit Default: TrimbleMaps.Common.DistanceUnit.MILES
Distance units as miles or kilometers.
options.trkLCV boolean Indicates whether the truck is a multi-trailer or longer combination vehicle.
options.trkUnits Common.TruckUnit Default: TrimbleMaps.Common.TruckUnit.ENGLISH
Sets truck dimensions as English or Metric.
options.trkHeight number The height of the vehicle in feet and inches or meters depending on units. Example 13'6" or 4.1148.
options.trkLength number The length of the vehicle in feet and inches or meters depending on units. Example 13'6" or 4.1148.
options.trkWidth number The width of the vehicle in feet and inches or meters depending on units. Example 13'6" or 4.1148.
options.trkWeight number The weight of the vehicle in pounds or kilograms depending on units.
options.trkAxles number Default: 5
The number of axles on the vehicle; acceptable values are 2 through 14.
options.trkMaxWeightPerAxleGroup number Weight per axle
options.trkTireCount number Tire count
options.ferryDiscourage boolean Default: false
Indicates whether or not to discourage the use of ferries when creating the route.
options.inclFerryDist boolean Default: true
Indicates whether or not to include ferry distances in mileage calculations of reports.
options.fuelUnits Common.FuelUnit Default: TrimbleMaps.Common.FuelUnit.GALLONS
Fuel units as gallons and liters.
options.truckConfig Common.TruckConfig Default: TrimbleMaps.Common.TruckConfig.NONE
The vehicle style.
options.inclTollData boolean Default: true
Indicates whether or not reports should calculate toll costs in reports.
options.fuelEconLoad number The fuel efficiency (distance units per fuel units) when loaded. Used for reports.
options.fuelEconEmpty number The fuel efficiency (distance units per fuel units) when empty. Used for reports.
options.costPerFuelUnit number The cost per fuel unit of fuel. Used for reports.
options.costGHG number The cost of greenhouse gas in lbs. per fuel unit. Used for reports.
options.costMaintLoad number The maintenance cost per distance unit when loaded. Used for reports.
options.costMaintEmpty number The maintenance cost per distance unit when empty. Used for reports.
options.costTimeLoad number The time cost per mile/km when loaded. Used for reports.
options.costTimeEmpty number The time cost per mile/km when empty. Used for reports.
options.tollCurrency Common.TollCurrency Default: TrimbleMaps.Common.TollCurrency.USD
options.exchangeRate number The change rate to convert US dollars to Canadian dollars. Used for reports.
options.tollPlan string Toll discount program. Only valid if the user has quarterly toll data privileges and inclTollData is set to true.
options.custRdSpeeds boolean Indicating whether or not to use custom road speeds.
options.useEUTollsReport boolean Indicating whether EU toll report should be reported.
options.useNonNaTolls boolean Indicating whether SA toll report should be reported.
options.includeRoadClass boolean Indicating whether the RoadClass will be included in the report.
options.citeInt number The cite interval to be used when generating a geotunnel report. The minimum value is 0.1. Used for reports.
options.region Common.Region Default: TrimbleMaps.Common.Region.NA
The data region in which the route stops are located.
options.dataVersion Common.DataVersion
options.reportType Array Default: [TrimbleMaps.Common.ReportType.MILEAGE]
The data region in which the route stops are located.
options.elevLimit number Elevation limit when generating a route
options.hosEnabled boolean Gets or sets whether HoursOfService is enabled.
options.hosRemDriveTimeUntilBreak number Gets or sets the available driving hours at origin before the driver needs to take a rest break. The format is in seconds.
options.hosRemDriveTime number Gets or sets the available driving hours at origin until the end of work day. The format is in seconds.
options.hosRemOnDutyTime number Gets or sets the available On-Duty hours available at origin until the end of work day. The format is in seconds.
options.hosRuleType Common.HoSScheduleType Gets or sets the hours of service rule currently in use.
options.hosRemCycleDutyTime number Gets or sets the available Cycle duty time at origin until Cycle reset. The format is in seconds.
options.hosCycleTimeGains Array<number> The list of cycle time gains per day. The format is in seconds.
options.hosLastCycleResetDateTime string The last cycle reset for Canadian hours of service
options.hosLast24HourBreakDateTime string The date and time of the last off duty break that was at least 24 consecutive hours for Canadian hours of service.
options.hosRemainingCanadaOnDutyTime number The available On-Duty hours available at origin until the end of work day. The format is in seconds.
options.hosRemainingDriveTimeUntilBreakDriver2 number The available driving hours at origin before the driver needs to take a rest break. The format is in seconds. Used only in Team Driving.
options.hosRemainingDriveTimeDriver2 number The available driving hours at origin until the end of work day. The format is in seconds. Used only in Team Driving.
options.hosRemainingOnDutyTimeDriver2 number The available On-Duty hours available at origin until the end of work day. The format is in seconds. Used only in Team Driving.
options.hosRemainingCycleDutyTimeDriver2 number The available Cycle duty time at origin until Cycle reset. The format is in seconds. Used only in Team Driving.
options.hosCycleTimeGainsDriver2 Array<number> The list of cycle time gains per day. The format is in seconds. Used only in Team Driving.
options.hosLastCycleResetDateTimeDriver2 string The time of the last cycle reset for Canadian hours of service. Used only in Team Driving.
options.hosLast24HourBreakDateTimeDriver2 string The date and time of the last off duty break that was at least 24 consecutive hours for Canadian hours of service. Used only in Team Driving.
options.hosRemainingCanadaOnDutyTimeDriver2 number The available On-Duty hours available at origin until the end of work day. The format is in seconds. Used only in Team Driving.
options.hosAlternateHoSRuleType number The alternate Hours of Service rule type to use if crossing international borders between the US and Canada.
options.hosRemainingTimeUntilFullDayBreak number The available On-Duty hours available at origin until the driver must take a 24 hour break.
options.hosRemainingTimeUntilFullDayBreakDriver2 number The available On-Duty hours available for Driver 2 at origin until the driver must take a 24 hour break. Used for Canada Cycle Two only. The format is in seconds.
options.hosRemainingDrivingTimeInWeek number The available Driving hours available at origin until the driver must a break. Used for Europe only. The format is in seconds.
options.hosRemainingOnDutyTimeInDay number The available On Duty Time In Day hours available at origin until the driver must a break. Used for Europe only. The format is in seconds.
options.hosRemainingConsecutiveDrivingTime number The available Consecutive Driving hours available at origin until the driver must a break. Used for Europe only. The format is in seconds.
options.hosRemainingFortnightlyTime number The available Fortnightly hours available at origin until the driver must a break. Used for Europe only. The format is in seconds.
options.hosCurrentOffDutyTime number The rest time already taken at a stop. Used for NA and Europe, regular and team driving. The format is in seconds.
options.hosCurrentOffDutyTimeDriver2 number The rest time already taken at a stop. Used for NA and Europe, regular and team driving. The format is in seconds.
options.hosUseCycleReset boolean Whether we do full cycle time reset or not.
options.hosTerminalDayStartTime string The time of day used to determine when a 24-hour period defining a ‘day’ starts. The format should be “HH:mm:sszzz”
options.hosUseCustomPlaces boolean Whether to use custom places for HOS rest stops.
options.hosTeamDriving boolean Whether there are team drivers.
options.hosShortBreakDuration number The short break duration. The format is in seconds. CustomBreakDurations
options.hosEndOfDutyBreakDuration number The end of duty break duration. The format is in seconds. CustomBreakDurations
options.hosCycleResetBreakDuration number The cycle reset break duration. The format is in seconds. CustomBreakDurations
options.hosDriverSwitchBreakDuration number The driver switch break duration. The format is in seconds. CustomBreakDurations
options.hosBorderCrossingWaitDuration number The time spent waiting at border crossings. The format is in seconds. CustomBreakDurations
options.hosBreakTimeInDayDuration number The break time in day duration. The format is in seconds. Used for HOS Europe only. CustomBreakDurations
options.hosBreakTimeInWeekDuration number The break time in week duration. The format is in seconds. Used for HOS Europe only. CustomBreakDurations
options.hosMaxAlternateRestStops number Whether the maximum number of Alternate Rest Stops to be displayed in the report. Defaults to 0.
options.hosSkipRestStopInsertion boolean Whether to skip inserting rest stops in the route
options.hosActiveDriver number Whether the active driver at the beginning of the trip. Used for Team Driving.
options.hosMaxDrivingTimeInDay number The maximum driving time allowed in a day. Used for HOS Europe only
options.hosMaxOnDutyTimeInDay number The maximum On-Duty time allowed in a day. Used for HOS Europe only
options.hosMaxOnDutyTimeInWeek number The maximum On-Duty time allowed in a week. Used for HOS Europe only
options.hosAdverseConditionException boolean Indicates where adverse driving conditions are present. HOS clock are extended by 2 hours due to the adverse driving condition exception.
options.hosPOIStopsReturned boolean Indicates whether POI Rest Stops will be returned, or only Lat/Lon Rest Stops will be returned.
options.hosHOSWindowStart number The start time of the window during the trip may insert an HOS Rest Stop
options.hosHOSWindowEnd number The end time of the window during the trip may insert an HOS Rest Stop
options.maintainHeading boolean When set, a vehicle will attempt to avoid u-turns at intermediate stops and instead leave the stop in the same direction it entered it.
options.sideOfStreetAdherence Common.SideOfStreetAdherenceLevel Represents the levels of adherence that apply a cost to a route if its destination is on the opposite side of the street.
options.governorSpeedLimit number Maximum average road speed to use in route calculations that overrides all other road speeds when they are above this value.
options.useAvoidsAndFavors boolean Indicating whether or not to use avoids and favors
options.useSites boolean Default: false
options.vehicleProfile Common.TruckConfig Provides the ability to load a vehicle profile which includes vehicle dimensions, route costs and routing options for a specific vehicle class.
options.refrigerated boolean Indicates whether the vehicle is a refrigerated truck.
options.fuelType Common.FuelType Fuel type
options.fuelConsumption number Indicates the fuel consumption of the vehicle.
options.trafficLookaheadDistance number Distance in miles for which we will gather traffic for the route.
options.avoidState Array<string> A list of states are avoided, for example [‘NJ’, ‘PA’]. ISO2 code.
options.avoidCountry Array<string> A list of countries are avoided, for example [‘US’, ‘CA’]. ISO2 code.
options.favorState Array<string> A list of states are in favor.
options.favorCountry Array<string> A list of countries are in favor.
options.includeTrimblePlaceIDs boolean Indicates use Trimble placeIds from while the processing route
options.useCrossStreetTurnAvoidance boolean Turns avoid cross street turns logic on or off.
options.congestionZonesOpen boolean Whether or not routes can pass through congestion zones. Default: true
options.lowEmissionZonesOpen boolean Whether or not routes can pass through low emission zones. Default: true
options.displayRestrictions Common.DisplayRestrictionsType ALWAYS_OFF - Always Off
ALWAYS_ON - Always On
BASED_ON_TRUCK_RESTRICTIONS - Based on Truck Profile
options.profileName string Profile name
options.profileId string Profile Id
options.isDraggable boolean Default: false
options.dragOptions DragRouteOptions Options for customizing route dragging behavior, such as snapping the route path to a nearby road link that is visible.
options.assetId string The ID of the asset (device, vehicle or driver) associated.
options.estimatedTimeOpts string Estimated time options allow you to specify either a day of the week or a specific date and the time for which you would like you depart from your origin or arrive at your destination.
options.useTraffic boolean Default: false
Indicates whether or not use traffic which is only used in conjunction with fastest routing.
options.includeVehicleRestrictedCleanupPoints boolean Boolean that designates if the customer wants the vehicle restricted cleanups to be separated from the main coordinate list and returned separately.
options.trlType Common.TrailerType Default: TrimbleMaps.Common.TrailerType.NONE
Type of the trailer. For Toll Detail reports in Europe.
options.trlCount number Default: 0
Number of trailers and semi-trailers. For Toll Detail reports in Europe.
options.trlMaxHt string Max height of the trailer in feet and inches, or meters depending on units. For Toll Detail reports in Europe.
options.trlMaxWt number Max weight of the trailer in pounds or kilograms depending on units. For Toll Detail reports in Europe.
options.trlMaxAxles number Default: 1
Max number of axles on the trailer. Acceptable values are 1 - 8. For Toll Detail reports in Europe.
options.isHybrid boolean Default: false
Indicates whether vehicle has a hybrid engine. For Toll Detail reports in Europe.
options.emiType Common.EmissionType Default: TrimbleMaps.Common.EmissionType.EUROVI
The emission type of the engine. For Toll Detail reports in Europe.
options.minPoll boolean Default: false
Indicates whether the vehicle is a minimum vehicle pollution. For Toll Detail reports in Europe.
options.frameRoute boolean Default: undefined
Indicates whether the center point and zoom level of the map will be adjusted to show the route in full frame. Only when it sets to false, the route will not be framed.
options.showStops boolean Default: undefined
Indicates whether the stops are displayed. After it is set, it can’t be changed.
options.congestionZone Common.ZoneType Congestion zone value
options.lowEmissionZone Common.ZoneType Low emission zone value
options.ultraLowEmissionZone Common.ZoneType Ultra low emission zone value
options.overrideClass Common.ClassOverride Default: TrimbleMaps.Common.ClassOverride.NONE
Represents type of class overrides.
options.requestMethod Common.RequestMethod Default: undefined. Uses HTTP GET method as default. Set the request method to POST to use HTTP POST method. Not every route option is supported by ‘GET’ method.
options.frameOptions Object A Map#fitBounds options object used to frame the route on the map when frameRoute is set to true. Default is 50px padding.
options.showArrows boolean Default false
Indicates whether direction arrows are drawn on top of the route line.
options.arrowOptions ArrowOptions Options for customizing the vizualization of route arrows.
options.isVisible boolean Default: true
Indicates whether the route will be visible when added to the map.
options.hubRouting boolean Default: false
Indicates whether or not to enable hub routing. Set to true to enable hub routing. When hub routing is enabled, drag routing and route optimizaion will be disabled.
options.styleChangeFrameRoute boolean Default: undefined
If it is set to true or false, options.frameRoute will be ignored temporarily and route will or will not be framed when style changes. If not set or set to null, options.frameRoute will be used.

Example 

var route = new TrimbleMaps.Route({
    routeId: 'myRoute',
    routeWidth: 8, // or {stops: [[10, 7],[15, 9],[19, 11]]}
    stops: [
        new TrimbleMaps.LngLat(-74.566234, 40.499440),
        new TrimbleMaps.LngLat(-74.629749, 40.261187)
    ],
    routeType: TrimbleMaps.Common.RouteType.SHORTEST,
    frameRoute: false,
    showStops: false,
    overrideClass: TrimbleMaps.Common.ClassOverride.FIFTY_THREE,
    requestMethod: TrimbleMaps.Common.RequestMethod.POST
  })
  .addTo(map);

Extends

Methods

_updateStopsThenGetRoute()

_updateStopsThenGetRoute(stops?: Object[]): void

Gets route after updating stops.

Parameters

Parameter Type Description
stops? Object[] Array. Route stops

Returns

void

addStopIcon()

addStopIcon(stopType: string, url: string): void

Adds stop icon

Parameters

Parameter Type Description
stopType string string. Valid values are 'start', 'end', 'stop'.
url string string. Icon URL

Returns

void

addStopMarkers()

addStopMarkers(options: RouteOptions, isActive: boolean): Route

Add Stops on the map without route line

Parameters

Parameter Type
options RouteOptions
isActive boolean

Returns

Route

Route this

addTo()

addTo(map: Map): Route

Attaches the route to a map

Parameters

Parameter Type Description
map Map Map. The map used for displaying the route.

Returns

Route

  • Route. this

canRedo()

canRedo(): boolean

Can redo

Returns

boolean

  • boolean. returns true if can redo, otherwise false

canUndo()

canUndo(): boolean

Can undo

Returns

boolean

  • boolean. returns true if can undo, otherwise false

disableRouteStack()

disableRouteStack(): void

Disables route undo, redo stack.

Returns

void

enableRouteStack()

enableRouteStack(): void

Enables route undo, redo stack. It is better either enabling undo-redo feature or the removing stop feature. It is not recommended to use both features at the same time.

Returns

void

frame()

frame(): Route

Sets the map view to fit the route.

Returns

Route

  • Route. this

frameRoute()

frameRoute(): Route

Returns

Route

  • Route. this

Deprecated

Sets the map view to fit the route.

getBottomLayerId()

getBottomLayerId(): string

Gets the bottom layer id for this route.

Returns

string

  • string. layer id or undefined

getReports()

getReports(options: RouteOptions): void

Gets reports for the route options

Parameters

Parameter Type Description
options RouteOptions RouteOptions. The route options used for the reports.

Returns

void

getRouteId()

getRouteId(): string

Gets the Route ID

Returns

string

  • string. ID of the route

getRouteWithNewStop()

getRouteWithNewStop(newStop: LngLat, routeLegPosition: number, newStopOption?: StopOptions): void

Inserts a stop to a route after a given route leg, then gets the route.

Parameters

Parameter Type Description
newStop LngLat LngLat. A stop
routeLegPosition number number. The sequence number of a route leg.
newStopOption? StopOptions Optional: Stop option of the new stop to be added instead of only LngLat.

Returns

void

isVisible()

isVisible(): boolean

Returns true if the layer is enabled.

Returns

boolean

  • boolean. A boolean indicating the visibility of the layer.

listens()

listens(type: string): boolean

Returns a true if this instance of Evented or any forwardeed instances of Evented have a listener for the specified type.

Parameters

Parameter Type Description
type string The event type

Returns

boolean

true if there is at least one registered listener for specified event type, false otherwise

Inherited from

Evented.listens

moveLayer()

moveLayer(beforeId?: string): Route

Moves route layers to a different z-position. The route will be inserted before the layer with ID beforeId, or appended on the top of the map if beforeId is omitted.

Parameters

Parameter Type Description
beforeId? string string. Optional ID of an existing layer to insert before

Returns

Route

  • Route. this

Example 

const myRoute1 = new TrimbleMaps.Route();
myRoute1.addTo(map);
myRoute1.moveLayer('layerId');

off()

off(type: string, listener: Listener): Route

Removes a previously registered event listener.

Parameters

Parameter Type Description
type string The event type to remove listeners for.
listener Listener The listener function to remove.

Returns

Route

Inherited from

Evented.off

on()

on(type: string, listener: Listener): this

Adds a listener to a specified event type.

Parameters

Parameter Type Description
type string The event type to add a listen for.
listener Listener The function to be called when the event is fired. The listener function is called with the data object passed to fire, extended with target and type properties.

Returns

this

Inherited from

Evented.on

once()

once(type: string, listener?: Listener): Promise<any> | Route

Adds a listener that will be called only once to a specified event type.

The listener will be called first time the event fires after the listener is registered.

Parameters

Parameter Type Description
type string The event type to listen for.
listener? Listener The function to be called when the event is fired the first time.

Returns

Promise<any> | Route

this or a promise if a listener is not provided

Inherited from

Evented.once

redo()

redo(): void

Redo route drag

Returns

void

remove()

remove(): Route

Removes the route from a map

Returns

Route

  • Route. this

Example 

var route = new TrimbleMaps.Route().addTo(map);
route.remove();

setDraggable()

setDraggable(isDraggable: boolean): Route

Sets the route’s ability to be modified by dragging

Parameters

Parameter Type Description
isDraggable boolean boolean. A boolean indicating whether or not the route is draggable.

Returns

Route

  • Route. this

setEventedParent()

setEventedParent(parent?: Evented, data?: any): Route

Bubble all events fired by this instance of Evented to this parent instance of Evented.

Parameters

Parameter Type
parent? Evented
data? any

Returns

Route

Inherited from

Evented.setEventedParent

setRouteState()

setRouteState(isActive: boolean): Route

Set the active route opacity 0.6 and enable the drag options and vice versa.

Parameters

Parameter Type Description
isActive boolean boolean. A boolean indicating the route is currently visible on the map.

Returns

Route

  • Route. this

setVisibility()

setVisibility(isVisible: boolean): Route

Set the layer visibility.

Parameters

Parameter Type Description
isVisible boolean boolean. A boolean indicating the visibility of the layer.

Returns

Route

  • Route. this

styleStopIcons()

styleStopIcons(style: StyleLayer): void

Changes stop icons styles. Following properties are assigned internally: id, type, source, layout[‘icon-image’], layout[’text-font’]

Parameters

Parameter Type Description
style StyleLayer Objec.t For detailed information, visit the Developer Portal

Returns

void

toggleVisibility()

toggleVisibility(): Route

Toggle layer visibility.

Returns

Route

  • Route. this

undo()

undo(): void

Undo route drag

Returns

void

update()

update(options: RouteOptions): void

Updates the route. It particularly updates route path, stop icons, route color, route opacity, route width, route arrow, drag routing. If more controlling over route stops styling is desirable, instead of using this function, construct a route with showStops setting to false, then adding custom stops icons uses addStopIcon function and styling them uses styleStopIcons function.

Parameters

Parameter Type Description
options RouteOptions RouteOptions. The route options to be updated.

Returns

void

Last updated June 11, 2025.
Contents