Package com.here.sdk.routing

Class RoutingEngine

java.lang.Object
com.here.NativeBase
com.here.sdk.routing.RoutingEngine
All Implemented Interfaces:
RoutingInterface
public final class RoutingEngine extends NativeBase implements RoutingInterface

Use the RoutingEngine to calculate a route from A to B with a number of waypoints in between.

Route calculation is done asynchronously and requires an online connection. The resulting route contains various information such as the polyline, route length in meters, estimated time to traverse along the route and maneuver data.

Note: The engine does not support an unlimited number of waypoints. The limit is defined by the HERE backend services and may change. For now, the maximum number of waypoints should be below 200. This value may change and it is not guaranteed to be stable. If you need to support very large lists of waypoints, consider to import a route (see importRoute() method) or use the OfflineRoutingEngine which supports an unlimited number of waypoints. The OfflineRoutingEngine is only available for Navigate licence.

  • Constructor Details

  • Method Details

    • refreshRoute

      @NonNull public TaskHandle refreshRoute(@NonNull RefreshRouteParameters refreshRouteParameters, @NonNull RoutingOptions routingOptions, @NonNull CalculateRouteCallback callback)

      Asynchronously refreshes a previously calculated route from the provided RouteHandle, updating the starting point and route metadata based on RoutingOptions. The route shape from the new starting point to the destination remains unchanged, and only metadata such as arrival time and traffic delays are updated.

      Parameters:
      refreshRouteParameters -

      The parameters used to refresh the route

      routingOptions -

      The options define the vehicle and route options used to calculate the route.

      callback -

      Callback object that will be invoked after refreshing the route. It is always invoked on the main thread.

      Returns:

      Handle that will be used to manipulate the execution of the task.

    • importRoute

      @NonNull public TaskHandle importRoute(@NonNull List<Location> locations, @NonNull RoutingOptions options, @NonNull CalculateRouteCallback callback)

      Asynchronously creates a route from a sequence of geographic coordinates very close to each other. The route shape will be kept as close as possible to the one provided. For best results please use 1Hz GPS data, or geographic coordinates that have a spacing of a few meters one from the other. For example, such a list of geographic coordinates can be extracted from a GPX trace or a route object from a 3rd party library. Very sparse data may be rejected by the service with an error.

      Note: Any restrictions applied to a transport type or provided options will be discarded and reported as violations in Section.getSectionNotices().

      Parameters:
      locations -

      The list of locations used to calculate the route. Note that only the Location.coordinates of a location are used to import the route.

      An RoutingError.INVALID_PARAMETER error is generated when the location list size is not in the range [2,50000].

      options -

      The options define the vehicle and route options to calculate the route.

      callback -

      Callback object that will be invoked after route calculation. It is always invoked on the main thread.

      Returns:

      Handle that will be used to manipulate the execution of the task.

    • importRoute

      @NonNull public TaskHandle importRoute(@NonNull List<Location> locations, @NonNull List<RouteStop> routeStops, @NonNull RoutingOptions options, @NonNull CalculateRouteCallback callback)

      Asynchronously creates a route from a sequence of geographic coordinates very close to each other. The route shape will be kept as close as possible to the one provided. For best results please use 1Hz GPS data, or geographic coordinates that have a spacing of a few meters one from the other. For example, such a list of geographic coordinates can be extracted from a GPX trace or a route object from a 3rd party library. Very sparse data may be rejected by the service with an error.

      Note: Any restrictions applied to a transport type or provided options will be discarded and reported as violations in Section.getSectionNotices() .

      Parameters:
      locations -

      The list of locations used to calculate the route. Note that only the Location.coordinates of a location are used to import the route.

      An RoutingError.INVALID_PARAMETER error is generated when the location list size is not in the range [2,50000].

      routeStops -

      The list of RouteStop's which contains index of location from locations list used for route stop and duration in seconds spent on stop.

      An RoutingError.INVALID_PARAMETER error is generated when the route stops list size is not in the range [1,locations.size()-2], any of location_index is < 1 or location_indexes are not unique.

      options -

      The options define the vehicle and route options to calculate the route.

      callback -

      Callback object that will be invoked after route calculation. It is always invoked on the main thread.

      Returns:

      Handle that will be used to manipulate the execution of the task.

    • importRoute

      @NonNull public TaskHandle importRoute(@NonNull RouteHandle routeHandle, @NonNull RoutingOptions options, @NonNull CalculateRouteCallback callback)

      Asynchronously recreates a route from the RouteHandle provided, i.e. refreshes a previously calculated route, with the specified RoutingOptions.

      A route handle can be invalid when the map data changes that is used by the HERE sdk to recreate the route. This happens regularly. Therefore, the route handle is not meant to be persisted for a longer time.

      Parameters:
      routeHandle -

      The route handle holding the route to be refreshed.

      options -

      The options define the vehicle and route options to calculate the route.

      callback -

      Callback object that will be invoked after refreshing the route. It is always invoked on the main thread.

      Returns:

      Handle that will be used to manipulate the execution of the task.

    • calculateTrafficOnRoute

      @NonNull public TaskHandle calculateTrafficOnRoute(@NonNull Route route, int lastTraveledSectionIndex, int traveledDistanceOnLastSectionInMeters, @NonNull CalculateTrafficOnRouteCallback callback)

      Asynchronously calculates the traffic along a route starting from the index of the last traveled route section and an offset (in meters) from the last visited position on the section. Call this when only the contained traffic information or the latest ETA duration is needed. This can be called periodically to retrieve updated ETA values during navigation.

      Note: Calling this method will trigger a new "HERE Traffic" transaction, for example, if you are using the Base Plan.

      Parameters:
      route -

      A Route calculated using the online routing engine. Its RouteHandle and the original route calculation options will be used to compute the traffic on the route. The original route remains untouched.

      lastTraveledSectionIndex -

      Indicates the index of the last traveled route section. Traveled part of the route won't be reused.

      traveledDistanceOnLastSectionInMeters -

      Offset, in meters, to the last visited position on the route section defined by the last traveled section index.

      callback -

      Callback object that will be invoked after route traffic has been calculated. It is always invoked on the main thread.

      Returns:

      Handle that will be used to manipulate the execution of the task.

    • calculateTrafficOnRoute

      @NonNull public TaskHandle calculateTrafficOnRoute(@NonNull Route route, int lastTraveledSectionIndex, int traveledDistanceOnLastSectionInMeters, double currentChargeInKilowattHours, @NonNull CalculateTrafficOnRouteCallback callback)

      Asynchronously calculates the traffic along an EV car route starting from the index of the last traveled route section and an offset in meters from the last visited position on the section. The field TrafficOnSpan.consumptionInKilowattHours will contain the power consumption in kilowatt-hours (kWh) necessary to traverse the span, and RoutePlace.chargeInKilowattHours, inside TrafficOnSection.departurePlace and TrafficOnSection.arrivalPlace, the estimated battery charge in kilowatt-hours (kWh) when leaving/arriving to a section. Note: Only EV cars are supported.

      Parameters:
      route -

      A Route calculated using the online routing engine. Its RouteHandle and the original route calculation options, along with EV related information like BatterySpecifications, will be used to compute the traffic on the route. The original route remains untouched.

      lastTraveledSectionIndex -

      Indicates the index of the last traveled route section. Traveled part of the route won't be reused.

      traveledDistanceOnLastSectionInMeters -

      Offset, in meters, to the last visited position on the route section defined by the last traveled section index.

      currentChargeInKilowattHours -

      Charge level of the vehicle's battery at the current location (in kWh). It must be non-negative and less than or equal to the value of BatterySpecifications.totalCapacityInKilowattHours, otherwise the BatterySpecifications instance is considered invalid. Sets BatterySpecifications.initialChargeInKilowattHours to the given value.

      callback -

      Callback object that will be invoked after route traffic has been calculated. It is always invoked on the main thread.

      Returns:

      Handle that will be used to manipulate the execution of the task.

    • setCustomOption

      @Nullable public RoutingError setCustomOption(@NonNull String name, @Nullable String value)

      Sets a custom option for routing backend queries. The custom option is applied to all the queries that RoutingEngine performs. For a complete list of available parameter names and their valid values, refer to HERE Routing API v8. Note: It's easy to set a wrong option that makes queries invalid, so make sure you read and understand the backend documentation.

      Parameters:
      name -

      An option name. If the engine already has an option with the same name, the option will be overwritten. The option name must be a non-empty string.

      value -

      An option value. If the value is null, the option will be removed. The option value must be a non-empty string.

      Returns:

      An optional error of setting the option. It's null if the option has been set successfully. It's RoutingError.INVALID_PARAMETER if the input name and/or value haven't passed internal validation.

    • calculateRoute

      @NonNull public TaskHandle calculateRoute(@NonNull List<Waypoint> waypoints, @NonNull RoutingOptions options, @NonNull CalculateRouteCallback callback)

      Asynchronously calculates a route from one point to another, passing through the given waypoints in the given order.

      Specified by:
      calculateRoute in interface RoutingInterface
      Parameters:
      waypoints -

      The list of waypoints used to calculate the route. The first element marks the starting position, the last marks the destination. Waypoints in between are interpreted as intermediate.

      An RoutingError.INVALID_PARAMETER error is generated when the waypoint list contains less than two elements or when the first and the last waypoints are not of type WaypointType.STOPOVER.

      options -

      Options describing routing options.

      callback -

      Callback object that will be invoked after route calculation. It is always invoked on the main thread.

      Returns:

      Handle that will be used to manipulate the execution of the task.

    • returnToRoute

      @NonNull public TaskHandle returnToRoute(@NonNull Route route, @NonNull Waypoint startingPoint, int lastTraveledSectionIndex, int traveledDistanceOnLastSectionInMeters, @NonNull CalculateRouteCallback callback)

      Asynchronously calculates a new route that leads back to the original route. The part of the original route which was already traveled by the user is ignored.

      Note: Stopover waypoints are guaranteed to be visited. Pass-through waypoints will be ignored. Additionally, the following route options are ignored: RouteOptions.alternatives, RouteOptions.arrivalTime, and RouteOptions.optimizationMode. Most route options are only applied to the newly calculated part back to the route.

      An application may use this method to submit a new starting point for a previously calculated route. This method tries to avoid a costly route re-calculation as much as possible. In case returning to the route without re-calculation is not possible, a new route is calculated, while trying to salvage the previous route as much as possible. However, a completely new route containing no part of the previous route is possible, too.

      Note that this function uses only a limited amount of map data around the new origin. Therefore, it may also work fine with temporarily cached map data. It may also copy some of the original route data into the new route.

      A typical use case is to await at least 3 RouteDeviation events before calling this method.

      • Or alternatively, wait at least 10 seconds after getting the first deviation event.
      • On top, the user experience can be improved by checking if the vehicle has moved at least 50 meters since calling this method for the last time.
      • Optionally, it may make sense to verify if the vehicle was ever following the route by checking if RouteDeviation.lastLocationOnRoute is set.

      Note that deviation events are sent each time a deviation is detected, i.e. for each new location update, regardless if the location has changed or not. More information can be found in the Developer Guide in the "Handle route deviations" section.

      Specified by:
      returnToRoute in interface RoutingInterface
      Parameters:
      route -

      A Route calculated using the online or offline route engine. For the offline case, It should not contain an indoor Section as such routes will fail. For the online case, it should have RouteHandle.

      startingPoint -

      The current location, for example, provided by a RouteDeviation event. The waypoint needs to be of type WaypointType.STOPOVER. Otherwise, an RoutingError.INVALID_PARAMETER error is generated.

      lastTraveledSectionIndex -

      Indicates the index of the last traveled route section. Traveled part of the route won't be reused.

      traveledDistanceOnLastSectionInMeters -

      Offset in meter to the last visited position on the route section defined by the last traveled section index.

      callback -

      Callback object that will be invoked after route calculation. It is always invoked on the main thread.

      Returns:

      Handle that will be used to manipulate the execution of the task.

    • dispose

      public void dispose()

      Cancels pending requests and closes the background worker thread. Note: This method should be called from main thread.

      Specified by:
      dispose in interface RoutingInterface