RoutePreferences - @magiclane/maps-sdk API Reference

Home > @magiclane/maps-sdk > RoutePreferences

RoutePreferences class

Comprehensive route calculation configuration for customizing routing behavior.

RoutePreferences centralizes all route calculation options including transport mode, vehicle profiles, avoidance settings (motorways, tolls, ferries, unpaved roads), traffic handling, algorithm selection, result detail levels, and alternative route handling. Set preferences before calling RoutingService.calculateRoute() to control how routes are computed.

Each transport mode supports specific profile configurations: - for cars, including fuel type and vehicle mass - for trucks, with dimensions and axle load constraints - for bicycles, supporting both standard and electric bikes - for walking or wheelchair-accessible routes

Common preferences include (fastest, shortest, economic), , , , , and strategies. Public transport options include departure/arrival times via and , transfer constraints, and sorting strategies. Emergency vehicle mode relaxes routing constraints.

Routing

Signature:

export declare class RoutePreferences extends GemAutoreleaseObject

Extends: GemAutoreleaseObject

Constructors

Constructor	Modifiers	Description
(constructor)(idOrOptions)		Creates a new set of routing preferences used to customize how routes are calculated. Can be called in two ways for backward compatibility: - `new RoutePreferences(id)` - Internal constructor with pointer ID - `new RoutePreferences(options)` - Public constructor with configuration options

Constructor

Modifiers

Description

(constructor)(idOrOptions)

Creates a new set of routing preferences used to customize how routes are calculated.

Can be called in two ways for backward compatibility: - new RoutePreferences(id) - Internal constructor with pointer ID - new RoutePreferences(options) - Public constructor with configuration options

Properties

Property	Modifiers	Type	Description
accurateTrackMatch		boolean	Enables accurate track matching for route-over-track computations. When true, the SDK uses more precise track matching algorithms during route calculation when track-based landmarks are provided. Default is `true`
accurateWaypointsApproach		boolean	Get accurate waypoints approach. An accurate approach implies that the route arrives at the waypoint on the drive side of the region. Default is `false`
algorithmType		PTAlgorithmType	Public transport algorithm type for determining departure or arrival time optimization. Default is `PTAlgorithmType.departure`
allowOnlineCalculation		boolean	Allows route calculation using online services when available. Default is `true`
alternativeRoutesBalancedSorting		boolean	Enables balanced sorting for alternative route results. Default is `true`
alternativesSchema		RouteAlternativesSchema	Schema defining how alternative routes are generated and returned. Default is `RouteAlternativesSchema.defaultSchema`
avoidBikingHillFactor		number	Hill avoidance factor for bicycle routes, ranging from 0.0 to 1.0.
avoidCarpoolLanes		boolean	Avoids carpool/HOV lanes when calculating routes. Default is `false`
avoidFerries		boolean	Avoids ferry crossings when calculating routes. Default is `false`
avoidGeofenceAntiAreas		string[]	Get the geofence anti-area avoidance IDs list An anti-area geofence is an area within which boundaries the route should remain during calculation. If is true and the route cannot stay in the requested boundaries, routing will fail.
avoidGeofenceAreas		string[]	Get the geofence area avoidance IDs list
avoidMotorways		boolean	Avoids motorways/highways when calculating routes. Default is `false`
avoidTollRoads		boolean	Avoids toll roads when calculating routes. Default is `false`
avoidTraffic		TrafficAvoidance	Traffic avoidance strategy for route calculation. Default is `TrafficAvoidance.none`
avoidTurnAroundInstruction		boolean	Avoids generating "Turnaround when possible" instructions during navigation. Default is `false`
avoidUnpavedRoads		boolean	Avoids unpaved roads when calculating routes. Default is `false`
bikeProfile		BikeProfileElectricBikeProfile	Bicycle routing profile for standard and electric bikes. Default is `null` (no bike profile)
buildConnections		boolean	Enables building route segment connections metadata. Default is `false`
buildConnectionsMaxLength	`readonly`	number	Get route connections build max length. Default is -1
buildTerrainProfile		BuildTerrainProfile	Controls whether terrain profile data is generated for the route. Default terrain profile disabled.
carProfile		CarProfile	Car routing profile with vehicle-specific constraints. Default is `null` (no car profile)
defaultEBikeProfile	`readonly`	ElectricBikeProfile	Default electric bike profile configuration.
departureHeading		DepartureHeading	Departure heading and accuracy for route calculation. Default heading and accuracy are -1 (no constraint).
emergencyVehicleExtraFreedomLevels		number	Extra freedom levels for emergency vehicle routing constraints. Only applies when is true. Default is `0`
emergencyVehicleMode		boolean	Enables emergency vehicle routing mode with relaxed constraints. Default is `false`
fitnessFactor		number	Bike & pedestrian routing fitness factor, ranging from 0.0 to 1.0. Default is `0.5` (normal/good shape)
ignoreRestrictionsOverTrack		boolean	Ignores map restrictions during route-over-track calculations. Default is `false`
immutableRoadblockAvoidance		boolean	Get the immutable roadblock avoidance state. If set, the algorithm rather fails than routing through roadblocks. Default is `false`
isTrackResume		boolean	Track resume mode for path-based routing with track landmarks. Default is `true`
maximumDistanceConstraint		boolean	Enables maximum distance constraints based on transport mode. Default is `true`
maximumTransferTimeInMinutes		number	Maximum transfer time between public transport connections, in minutes. Default is `300` (5 hours)
maximumWalkDistance		number	Maximum walking distance for public transport routes, in meters. Default is `5000` meters (5 km)
minimumTransferTimeInMinutes		number	Minimum transfer time between public transport connections, in minutes. Default is `1` minute
pathAlgorithm		RoutePathAlgorithm	Path calculation algorithm to use for routing. Default is `RoutePathAlgorithm.ml`
pathAlgorithmFlavor		RoutePathAlgorithmFlavor	Flavor variant of the selected path algorithm. Default is `RoutePathAlgorithmFlavor.magicLane`
pedestrianProfile		PedestrianProfile	Pedestrian routing profile for walking and wheelchair accessibility. Default is `PedestrianProfile.walk`
pointerId	`readonly`	any
resultDetails		RouteResultDetails	Level of detail to include in route calculation results. Default is `RouteResultDetails.full`
roundTripParameters		RoundTripParameters	Set parameters for roundtrip feature.
roundTripRandomSeed	`readonly`	number	Get roundtrip random seed.
roundTripRange	`readonly`	number	Get roundtrip range.
roundTripRangeType	`readonly`	RangeType	Get roundtrip range type.
routeGroupIdsEarlierLater		number[]	Route group IDs for earlier/later trip calculations in public transport. Default is an empty list
routeRanges		number[]	Route range values for isoline/isochrone calculations. Default is an empty list (no range calculation)
routeRangesQuality		number	Quality level for route range calculations, from 0 to 100. Default is `100` (maximum quality)
routeResultType	`readonly`	RouteResultType	Route result type indicating the format of the returned route. Default is `RouteResultType.path`.
routeType		RouteType	Primary route optimization criterion. Default is `RouteType.fastest`
routeTypePreferences		Set<RouteTypePreferences>	Additional route type preference flags. Default is `{RouteTypePreferences.none}`
sortingStrategy		PTSortingStrategy	Public transport route sorting strategy. Default is `PTSortingStrategy.bestTime`
timestamp		Date \| null	Local departure or arrival time for public transport routing. Default is `null` (current time)
transportMode		RouteTransportMode	Primary transport mode for route calculation. Default is `RouteTransportMode.car`
truckProfile		TruckProfile	Truck routing profile with vehicle-specific constraints. Default is `null` (no truck profile)
useBikes		boolean	Ensures bike accessibility for public transport routes. Default is `false`
useWheelchair		boolean	Ensures wheelchair accessibility for public transport routes. Default is `false`
vehicleRegistration	`readonly`	VehicleRegistration \| null	Returns the vehicle registration profile for the current transport mode. Extracts the relevant vehicle profile (CarProfile, TruckProfile, or ElectricBikeProfile) based on the selected . Returns null for pedestrian, public, and shared vehicle modes or when no profile is configured.

Methods

Method	Modifiers	Description
create(options)	`static`	Creates a new set of routing preferences used to customize how routes are calculated. These preferences control routing behavior such as transport mode, avoidance options, algorithm selection, profile overrides, and constraints for transfers, walking distance, and timing. Provide only the options you need; unspecified profile fields will fall back to default behavior. This constructor configures a request-level set of hints that influence route generation and result formatting.
dispose()

Method

Modifiers

Description

create(options)

static

Creates a new set of routing preferences used to customize how routes are calculated.

These preferences control routing behavior such as transport mode, avoidance options, algorithm selection, profile overrides, and constraints for transfers, walking distance, and timing. Provide only the options you need; unspecified profile fields will fall back to default behavior. This constructor configures a request-level set of hints that influence route generation and result formatting.

dispose()