Skip to main content

Advanced features

|

Compute route ranges

In order to compute a route range we need to:

  • Specify in the RoutePreferences the most important route preference (others can also be used):
    • setRouteRanges with a list of range values, one for each route we compute and a quality value [0, 100]. The quality representing the quality of the generated polygons. Measurement units are corresponding to the specified routeType (see the table below)
    • [optional] setTransportMode (by default ERouteTransportMode::RTM_Car)
    • [optional] setRouteType (can be RT_Fastest, RT_Economic, RT_Shortest - by default is RT_Fastest)
  • The list of landmarks used in calculateRoute will contain only one landmark, the starting point for the route range computation.
PreferenceMeasurement unit
fastestseconds
shortestmeters
economicWh
warning

Routes computed using route ranges are not navigable.

warning

The ERouteType::RT_Scenic route type is not supported for route ranges.

Route can be computed with a code like the following. It is a range route computation because it only has a simple Landmark and routeRanges contains values (in this case 2 routes will be computed).

// Define the departure.
Landmark startLandmark( "start", { 48.85682, 2.34375 });

// Define the route preferences.
// Compute 2 ranges, 30 min and 60 min
RoutePreferences routePreferences;
routePreferences.setRouteType( ERouteType::RT_Fastest );
routePreferences.setRouteRanges( { 1800, 3600 }, 100 );
        
RouteList resultedRoutes;

RoutingService().calculateRoute(resultedRoutes,
    { startLandmark },
    routePreferences,
    yourProgressListenerImpl
);
Note

The computed routes can be displayed on the map, just like any regular route, with the only difference that the additional settings RouteRenderSettings.m_fillColor is used to define the polygon fill color.

Compute path based routes​

A Path is a structure containing a list of coordinates (a track). It can be created based on:

  • custom coordinates specified by the user
  • coordinates recorded in a GPX file
  • coordinates obtained by doing a finger draw on the map

Sometimes we want to compute routes based on a list of one or more Path backed landmark(s) and optionally some regular Landmark(s). In this case the result will only contain one route. The path provided as waypoint track is used as a hint for the routing algorithm.

You can see an example below of a route computation over a path (the highlighted area represents the code necessary to create the list with one element of type landmark built based on a path):

CoordinatesList coords{
    { 40.786, -74.202 },
    { 40.690, -74.209 },
    { 40.695, -73.814 },
    { 40.782, -73.710 }
};

// Create the path.
Path path( coords );

// Declare a landmark that will hold the path.
Landmark pathLandmark( "path landmark", {} );

// Set the path data to the landmark.
RouteBookmarks::setWaypointTrackData( pathLandmark, path );

// The landmark list containing the path landmark.
LandmarkList landmarkList{ pathLandmark }; // other landmarks can be added as well, simple or with path data

// Define the route preferences.
auto routePreferences = RoutePreferences();

RouteList resultedRoutes;

RoutingService().calculateRoute(resultedRoutes,
    landmarkList,
    routePreferences,
    yourProgressListenerImpl
);

Computing a route based on a GPX file​

You can compute a route based on a GPX file by using the path based landmark described in the previous section. The only difference is how we create the Path.

DataBuffer gpxDataBuf; // fill gpxDataBuf with GPX data containing a track

Path path( gpxDataBuf, (int) EPathFileFormat::PFF_Gpx, yourPathCreationProgressListenerImpl);
// Wait until the path creation is complete.

// Declare a landmark that will hold the path.
Landmark pathLandmark( "path landmark", {} );

// Set the path data to the landmark.
RouteBookmarks::setWaypointTrackData( pathLandmark, path );

// The landmark list containing the path landmark.
LandmarkList landmarkList{ pathLandmark }; // other landmarks can be added as well, simple or with path data

// Define the route preferences.
auto routePreferences = RoutePreferences();
routePreferences.setTransportMode(ERouteTransportMode::RTM_Bicycle);

RouteList resultedRoutes;

RoutingService().calculateRoute(resultedRoutes,
    landmarkList,
    routePreferences,
    yourProgressListenerImpl
);

The resulted List<Landmark> will only contain one element, a path based Landmark.

Compute public transit routes​

In order to compute a public transit route we need to set the transportMode field in the RoutePreferences like this:

// Define the route preferences with public transport mode.
RoutePreferences routePreferences;
routePreferences.setTransportMode( ERouteTransportMode::RTM_Public );
warning

Public transit routes are not navigable.

The full source code to compute a public transit route and handle it could look like this:

// Define the departure.
Landmark departureLandmark("departure", { 45.6646, 25.5872 } );

// Define the destination.
Landmark destinationLandmark("destination", { 45.6578, 25.6233 } );

// Define the route preferences with public transport mode.
RoutePreferences routePreferences;
routePreferences.setTransportMode(ERouteTransportMode::RTM_Public);

RouteList resultedRoutes;

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

// Wait for the operation to complete (replace with your own synchronization mechanism).
WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl  ), 15000 );

if (!resultedRoutes.empty()) 
{
    // Display the routes on map.
    bool mainRoute = true;
    for (auto route : resultedRoutes) 
    {
        mapView->preferences().routes().add(route, mainRoute);
        mainRoute = false;
    }

    // Convert normal route to PTRoute
    auto ptRoute = resultedRoutes.front().toPTRoute();

    // Convert each segment to PTRouteSegment
    auto ptSegments = ptRoute.getSegments();

    for(auto segment : ptSegments) 
    {
        auto ptSegment = segment.toPTRouteSegment();
        ETransitType transitType = ptSegment.getTransitType();

        if(ptSegment.isCommon()) 
        { // PT segment
            List<RouteInstruction> ptInstructions = segment.getInstructions();
            for(auto instr : ptInstructions) 
            {
                auto ptInstr = instr.toPTRouteInstruction();
                // handle public transit instruction
                String stationName = ptInstr.getName();
                auto departure = ptInstr.getDepartureTime();
                auto arrival = ptInstr.getArrivalTime();
                // ...
            }
        } 
        else 
        { // walk segment
            List<RouteInstruction> instructions = ptSegment.getInstructions();
            for(auto walkInstr : instructions) 
            {
                // handle walk instruction
            }
        }
    }
}

Once routes are computed, if the computation was for public transport route, you can convert a resulted route to a public transit route via toPTRoute(). After that you have full access to the methods specific to this kind of route.

A public transit route is a sequence of one or more segments. Each segment is either a walking segment, either a public transit segment. You can determine the segment type based on the ETransitType.

ETransitType can have the following values: TT_Walk, TT_Bus, TT_Underground, TT_Railway, TT_Tram, TT_WaterTransport, TT_Other, TT_SharedBike, TT_SharedScooter, TT_SharedCar, TT_Unknown.

tip

Other settings related to public transit (such as departure/arrival time) can be specified within the RoutePreferences object passed to the calculateRoute method:

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

RoutePreferences customRoutePreferences;
customRoutePreferences.setTransportMode(ERouteTransportMode::RTM_Public);
// The arrival time is set to one hour from now.
customRoutePreferences.setAlgorithmType( EPTAlgorithmType::PTAT_Arrival);
customRoutePreferences.setTimestamp( now + oneHour );

// Sort the routes by the best time.
customRoutePreferences.setSortingStrategy(EPTSortingStrategy::PTSS_Best_Time);
           
// Accessibility preferences
customRoutePreferences.setUseBikes(false);
customRoutePreferences.setUseWheelchair( false );

Export a Route to file​

The exportToFile method allows you to export a route from RouteBookmarks into a file on disk. This makes it possible to store the route for later use or share it with other systems.

The file will be saved at the exact location provided in the path parameter, so always ensure the directory exists and is writable.

auto error = yourRouteBookmarksObj->exportToFile(index, filePath);
TIP

When exporting a route, make sure to handle possible errors:

  • error::KNotFound - This occurs if the given route index does not exist.
  • error::KIo - This occurs if the file cannot be created or written to.

Export a Route as String​

The exportAs method allows you to export a route into a textual representation. The returned value is a String containing the full route data in the requested format.
This makes it easy to store the route as a file or share it with other applications that support formats like GPX, KML, NMEA, or GeoJSON.

DataBuffer dataGpx = resultedRoutes.front().exportAs(EPathFileFormat::PFF_Gpx);
// You now have the full GPX as a string, written inside a DataBuffer.
Last updated on