Handling RoutePreferences

Before computing a route, we need to specify some route options.

The most generic supported route options are briefly presented in the following table.

Preference	Explanation	Default Value
setAccurateTrackMatch	Enables accurate track matching for routes.	true
setAllowOnlineCalculation	Allows online calculations.	true
setAlternativeRoutesBalancedSorting	Balances sorting of alternative routes.	true
setAlternativesSchema	Defines the schema for alternative routes.	ERouteAlternativesSchema::AS_Default
setAutomaticTimestamp	Automatically includes a timestamp.	true
setDepartureHeading	Sets departure heading and accuracy.	heading: -1, accuracy: 0
setIgnoreRestrictionsOverTrack	Ignores restrictions over the track.	false
setMaximumDistanceConstraint	Enables maximum distance constraints.	true
setPathAlgorithm	Algorithm used for path calculation.	ERoutePathAlgorithm::PA_ML
setPathAlgorithmFlavor	Flavor for the path algorithm.	ERoutePathFlavor::PF_ML
setResultDetails	Level of details in the route result.	ERouteResultDetails::RD_Full
setRouteRanges	Ranges for the routes (isochrones). Quality of the resulted polygons.	[], quality: 100
setRouteType	Preferred route type.	ERouteType::RT_Fastest
setTimestamp	Custom timestamp for the route. Used with PT Routes to specify the desired arrival/departure time. It represents the local time of the route start/end.	empty (current time will be used)
setTransportMode	Transport mode for the route.	ERouteTransportMode::RTM_Car

warning

In order to compute the timestamp in the required format, please check the snippet below:

Landmark departureLandmark ( "departure", { 45.65, 25.60} );
Landmark destinationLandmark ( "destination", { 46.76, 23.58 } );

auto now = Time::getUniversalTime();
LargeInteger oneHour = 3600 * 1000; // Milliseconds in one hour

TimezoneResult result;

TimezoneService().getTimezoneInfo(
	result,
	departureLandmark.getCoordinates(),
	now + oneHour, // Compute time for one hour later
	yourProgressListenerImpl
	);

// When notifyComplete is received in yourProgressListenerImpl, get the timestamp from the result
result.getLocalTime();
// Pass the timestamp to RoutePreferences

Check the Timezone Service guide for more details.

Enabling complex structures creation options are presented in the following table:

Preference	Explanation	Default Value
setBuildConnections	Enables building of route connections.	false, maxLengthM: -1
setBuildTerrainProfile	Enables building of terrain profile.	false, minVariation: -1

Route specific options for custom profiles are presented in the following table:

Preference	Explanation	Default Value
setBikeProfile	Profile configuration for bikes.	EBikeProfile::BP_City
setCarProfile	Profile configuration for cars.	CarProfile()
setEvProfile	Profile configuration for electric vehicles.	EVProfile()
setPedestrianProfile	Profile configuration for pedestrians.	EPedestrianProfile::PP_Walk
setTruckProfile	Profile configuration for trucks.	TruckProfile()

Avoid options are presented in the following table:

Preference	Explanation	Default Value
setAvoidBikingHillFactor	Factor to avoid biking hills.	0.5
setAvoidCarpoolLanes	Avoids carpool lanes.	false
setAvoidFerries	Avoids ferries in the route.	false
setAvoidMotorways	Avoids motorways in the route.	false
setAvoidTollRoads	Avoids toll roads in the route.	false
setAvoidTraffic	Strategy for avoiding traffic.	ETrafficAvoidance:TA_None
setAvoidTurnAroundInstruction	Avoids turn-around instructions.	false
setAvoidUnpavedRoads	Avoids unpaved roads in the route.	false

Emergency vehicles preferences are shown in the following table:

Preference	Explanation	Default Value
setEmergencyVehicleMode	Enables emergency vehicle mode.	false, extraFreedom = 0

Public Transport preferences are shown in the following table:

Preference	Explanation	Default Value
setAlgorithmType	Algorithm type used for routing.	EPTAlgorithmType::PTAT_Departure
setMinimumTransferTimeInMinutes	Minimum transfer time in minutes.	1
setMaximumTransferTimeInMinutes	Sets maximum transfer time in minutes.	300
setMaximumWalkDistance	Maximum walking distance in meters.	5000
setSortingStrategy	Strategy for sorting routes.	EPTSortingStrategy::PTSS_Best_Time
setRouteTypePreferences	Preferences for route types.	ERouteTypePreferences:RTP_None
setUseBikes	Enables use of bikes in the route.	false
setUseWheelchair	Enables wheelchair-friendly routes.	false
setRouteGroupIdsEarlierLater	IDs for earlier/later route groups.	[]

A short example of how they can be used to compute the fastest car route and also to compute a terrain profile is presented below:

RoutePreferences routePreferences;

routePreferences.setTransportMode( ERouteTransportMode::RTM_Car );
routePreferences.setRouteType( ERouteType::RT_Fastest );
routePreferences.setBuildTerrainProfile(true);

There are also properties that can't be set and only can be obtained for a route, in order to know how that route was computed:

Preference	Explanation	Default Value
getRouteResultType	Type of route result.	ERouteResultType::RRT_Path

Computing truck routes

To compute routes for trucks we can write code like the following by initializing the truckProfile field of RoutePreferences:

// Define the departure.
Landmark departureLandmark( "departure", { 48.87126, 2.33787} );

// Define the destination.
Landmark destinationLandmark ( "destination", { 51.4739, -0.0302 } );

TruckProfile truckProfile;
truckProfile.height = 180; // cm
truckProfile.length = 500; // cm
truckProfile.width = 200; // cm
truckProfile.axleLoad = 1500; // kg
truckProfile.maxSpeed = 60; // km/h
truckProfile.mass = 3000; // kg
truckProfile.fuel = EFuelType::FT_Diesel;

// Define the route preferences with current truck profile and lorry transport mode.
RoutePreferences routePreferences;

routePreferences.setTruckProfile( truckProfile );
routePreferences.setTransportMode( ERouteTransportMode::RTM_Lorry ); // <- This field is crucial

RouteList resultedRoutes;

RoutingService().calculateRoute(resultedRoutes,
                { departureLandmark, destinationLandmark },
    routePreferences,
    yourProgressListenerImpl
);

EFuelType can have the following values: petrol, diesel, lpg (liquid petroleum gas), electric.

By default, all field except fuel have default value 0, meaning they are not considered in the routing. fuel by default is EFuelType::FT_Diesel.

Computing caravan routes

Certain vehicles, such as caravans or trailers, may be restricted on some roads due to their size or weight, yet still permitted on roads where trucks are prohibited.

To calculate routes for caravans or trailers, we can use the truckProfile field of RoutePreferences with the appropriate dimensions and weight.

// Define the departure.
Landmark departureLandmark( "departure", { 48.87126, 2.33787} );

// Define the destination.
Landmark destinationLandmark ( "destination", { 51.4739, -0.0302 } );

TruckProfile truckProfile;
truckProfile.height = 180; // cm
truckProfile.length = 500; // cm
truckProfile.width = 200; // cm
truckProfile.axleLoad = 1500; // kg

// Define the route preferences with current truck profile and lorry transport mode.
RoutePreferences routePreferences;

routePreferences.setTruckProfile( truckProfile );
routePreferences.setTransportMode( ERouteTransportMode::RTM_Car ); // <- This field is crucial to distinguish caravan from truck

RouteList resultedRoutes;

RoutingService().calculateRoute(resultedRoutes,
    { departureLandmark, destinationLandmark },
    routePreferences,
    yourProgressListenerImpl
);

At least one of the fields height, length, width or axleLoad must be set to a non-zero value in order for the settings to be taken into account during routing. If all these fields are set to 0 then a normal car route will be calculated.

Computing truck routes​

Computing caravan routes​

Computing truck routes

Computing caravan routes