Directions
The HERE SDK provides a full-fledged RoutingEngine
to calculate the best route directions from A to B, including multiple waypoints and localizable maneuver instructions for each turn.
Specify your preferences by setting the desired route type (fastest or shortest) and various route options (such as speed profiles, route restrictions, vignette options, and more) to find the perfect route that saves the most energy: With our advanced routing technology and our dedicated EV route planning support HERE helps you to make the planet cleaner and safer.
Feature overview:
- Calculate routes: Calculate routes with multiple waypoints for various transport modes.
- Isoline routing: Calculate isoline polygons to represent the area of reach from a given point based on time, distance or fuel consumption.
- Search along a route: Search for places along an entire route (this feature is described in the Search section).
- Import routes / route matching: You can import routes from other APIs.
- Offline routing: When no internet connection is available, you can switch to a dedicated offline routing engine to calculate routes on already cached map data or preloaded offline maps data.
Get Routes
The HERE SDK supports the following route types:
- Car route directions.
- Taxi route directions.
- Pedestrian route directions.
- Bicycle route directions.
- Truck route directions with highly customizable truck options.
- Scooter route directions.
- Bus route directions.
- Routes for electric vehicles to find the nearest charging stations (based on the calculated energy consumption and battery specifications).
- Public transit routes with highly customizable transit options (via
TransitRoutingEngine
).
Note
All transport modes are available for online route calculation with the RoutingEngine
. Some transport modes are also available for offline route calculation on cached map data or downloaded offline maps with the OfflineRoutingEngine
. An overview of the supported offline modes can be seen here.
Each route type is determined by one of the available route options such as CarOptions
or TruckOptions
: Find here all available route options for each supported transport mode. These options can be set to the available overloads of the route engine's calculateRoute()
method.
Start your trip by creating the route engine in this manner:
try {
routingEngine = new RoutingEngine();
} catch (InstantiationErrorException e) {
throw new RuntimeException("Initialization of RoutingEngine failed: " + e.error.name());
}
Creating a new RoutingEngine
instance can throw an error that we have to handle as shown above. For example, such an error can happen when the HERE SDK initialization failed beforehand.
Note
It is not possible to initialize this engine during the Application
's onCreate()
method. Any other point in time is fine. For example, a good place to initialize this engine may be in an Activity
's onCreate()
-method.
As a next step, you can calculate the route based on two waypoints - a starting location and a destination (both of type Waypoint
that holds a GeoCoordinates
instance). Below we set default CarOptions
to calculate a route that is optimized for cars:
Waypoint startWaypoint = new Waypoint(startGeoCoordinates);
Waypoint destinationWaypoint = new Waypoint(destinationGeoCoordinates);
List<Waypoint> waypoints =
new ArrayList<>(Arrays.asList(startWaypoint, destinationWaypoint));
routingEngine.calculateRoute(
waypoints,
new CarOptions(),
new CalculateRouteCallback() {
@Override
public void onRouteCalculated(@Nullable RoutingError routingError, @Nullable List<Route> routes) {
if (routingError == null) {
Route route = routes.get(0);
showRouteDetails(route);
showRouteOnMap(route);
logRouteViolations(route);
} else {
showDialog("Error while calculating a route:", routingError.toString());
}
}
});
You can call calculateRoute()
multiple times. For example, you can call it to calculate routes with different routing options in parallel.
Note
Tip: If a driver is moving, the bearing value can help to improve the route calculation: startWaypoint.headingInDegrees = location.bearingInDegrees;
.
Each route calculation will be performed asynchronously. You will get a Route
list or a RoutingError
that holds a possible error when completed. If all goes well, RoutingError
is null. In case of an error, the route list is null. For example, the engine cannot calculate routes if a route is not feasible for the specified mode of transportation.
Note
If there is no error, the route list will contain only one result. By specifying the number of route alternatives via the route options, you can request additional route variants. By default, a route will be calculated with no route alternatives.
The showRouteDetails()
-method from the code snippet above is used to show more route details including maneuver instructions. You can find the full source code in the accompanying example app. Maneuver instructions are also explained in greater detail below. The showRouteOnMap()
-method contains an example, how to render a route on the map. We will explain this shortly in the section below.
Note: Important
A route may contain a list of NoticeCode
values that describe potential issues after a route was calculated. For example, when a route should avoid tunnels and the only possible route needs to pass a tunnel, the Route
contains a notice that the requested avoidance of tunnels was violated.
- It is recommended to always check a calculated
Route
for possible violations. - The
NoticeCode
is part of a Notice
object. A list of possible Notice
objects can be accessed per Section
of a Route
. - The list will be empty, when no violation occurred.
- If any possible violation is not desired, it is recommended to skip routes that contain at least one violation.
However, an implementation may judge case by case depending on the requested route options and the actual list of NoticeCode
values. More about route options can be found in the next section. Important: For the sake of simplicity, the code snippets in this guide do not evaluate the possible enum values of a notice.
You can detect possible route notices with the following method:
private void logRouteViolations(Route route) {
for (Section section : route.getSections()) {
for (SectionNotice notice : section.getSectionNotices()) {
Log.e(TAG, "This route contains the following warning: " + notice.code.toString());
}
}
}
Note
Tip: All routes contain altitude values along the route. For example, to create an elevation profile for a planned bicycle trip.
Use Route Options for Each Transport Mode
For the example above, we have set a new CarOptions
instance to calculate a car route. You can calculate routes for other transport modes by using dedicated route options for each transport mode. The following route options exist:
-
CarOptions
to calculate car routes: route.requestedTransportMode
is TransportMode.car
. -
TruckOptions
to calculate truck routes: route.requestedTransportMode
is TransportMode.truck
. -
PedestrianOptions
to calculate routes for pedestrians: route.requestedTransportMode
is TransportMode.pedestrian
. -
EVCarOptions
and EVTruckOptions
to calculate routes for electric vehicles: route.requestedTransportMode
is TransportMode.car
or TransportMode.truck
. -
ScooterOptions
to calculate routes for scooters: route.requestedTransportMode
is TransportMode.scooter
. -
BicycleOptions
to calculate routes for bicycles: route.requestedTransportMode
is TransportMode.bicycle
. -
TaxiOptions
to calculate routes for taxis: route.requestedTransportMode
is TransportMode.taxi
. -
BusOptions
to calculate routes for buses: route.requestedTransportMode
is TransportMode.bus
. -
TransitRouteOptions
to calculate routes for public mass transit (only available via TransitRoutingEngine
): route.requestedTransportMode
is TransportMode.publicTransit
.
The TransportMode
is set by the routing engine after route calculation has been completed - while getRequestedTransportMode()
determines the transport mode from the route options, each Section
of a Route
can have a different transport mode: route.getSectionTransportMode()
provides the actual SectionTransportMode
that has to be used for a particular section - in addition to the transport modes from above, it lists also transport modes such as ferry
and carShuttleTrain
.
By default, when passing only start and destination waypoints, the resulting route will contain only one route Section
. Each route
object can contain more route sections depending on the number of set waypoints and transport modes. Sections act as a route leg that break a route into several logical parts. Find more about this here.
Although the main transport mode is specified by the user before calculating the route, the final transport modes are set by the routing engine per Section
.
Note
A Route
can contain more than one SectionTransportMode
. In such a case, the route will split into another Section
to indicate the change of the transport mode. Basically, changing the mode of transport requires a stop on a journey, for example, when leaving the car to take a ferry. However, full multimodal routing is not supported: If a car route includes as destination a sightseeing spot in a park then the last waypoint will be map-matched to the last location before the park that is reachable by car.
Such gaps can be detected by comparing the mapMatchedCoordinates
with the originalCoordinates
of a RoutePlace
object: An application can decide to fill the distance between these two coordinates with a new route calculation using a suitable transport mode as fallback - such modal routes can be composed with many different options as some users may prefer taking a taxi or public transit instead of taking a walk. Note that the HERE SDK supports such modal routes only as separate requests, so the application needs to implement the fallback logic.
Note that all geographic coordinates along a route are map-matched (also known as snap-to-road). If additional Waypoints
are added, they will be also map-matched and their original coordinates can be compared with the map-matched location inside a RoutePlace
that is indicating the beginning and the end of a Section
.
All of the available route options allow you to further specify several parameters to optimize the route calculation to your needs.
Each of the above options contains a field that holds a common RouteOptions
object. This option allows you to specify common options such as the number of route alternatives or the OptimizationMode
to find the optimal route based on travel time and route length.
Note
By default, a route will be calculated using the FASTEST
route mode.
Alternatively, you can change the algorithm. For example, if you want to reach your destination quickly and the length of the route is less important to you, select the FASTEST
route mode via RouteOptions
. Select SHORTEST
if you prefer a shorter route, and time is not so important.
To find the best route for you, the routing algorithm takes into account many different parameters. This does not mean the algorithm will always provide the absolute shortest or fastest route. For example, consider the following road network:
Illustration: Which route would you choose?
When you plan a trip from A to B, you may have the choice between four different roads. Let's assume that the green route represents a highway, then this road may be the fastest route, although it is longer than any of the other routes that would guide you through a city.
If you prefer to take the shortest route, the algorithm may favor the blue route, although the yellow and the red routes are shorter. Why is this so? The yellow road is the shortest route, of course, but it has to cross a river where a ferry has to be taken. This could be regarded by the algorithm as time-costly. As a result, it is possible to prefer the red or blue route instead of the yellow route, even though both are slightly longer.
Let's explore the other two options. When comparing the blue and the red route, the routing algorithm may recommend the blue route as the shortest although it is slightly longer than the red route: several turns are typically not beneficial to a driver. In this case, the red route contains more turns than the blue route, but the blue route may be the preferred route as it is only slightly longer. The routing algorithm penalizes turns and many other road properties, such as traffic lights or rail crossings that can slow a driver down.
Note
Along with the common routing options, the HERE SDK offers specialized options for the various supported transport modes, such as truck routing, where you can specify, for example, the dimensions of your truck to find only the suitable routes where your truck would fit - considering parameters such as road width or tunnel height.
While the resulting routes are optimized based on certain criteria, there may be situations where you don't want to rely on that. Imagine a city trip through Berlin - finding the fastest or shortest route may not be an option if you want to experience many sightseeing spots the city has to offer. In such cases, setting additional waypoints may be a good idea. Find an example below.
Get Truck Routes
The HERE SDK supports different transport modes (see above) for route calculation. Similar to the example above that shows how to calculate a route optimized for cars, you can also calculate routes for other transport types such as trucks.
While you can already get a route optimized for trucks by setting the default options, there are many more options available to find the best routes for a truck.
For example, TruckOptions
contains additional fields such as TruckSpecifications
to specify the dimensions of your truck, and more, that can be optionally applied to take the vehicle weight and other parameters into account.
More on truck routing can be found in the Truck Guidance section.
Get Public Transit Routes
Use the TransitRoutingEngine
to calculate public transit routes from A to B with a number of waypoints in between. You can find a PublicTransit example app on GitHub that shows how to do this.
Shape the Route with Additional Waypoints
By default, when setting only start and destination waypoints, the resulting route will contain only one route Section
. Each route object can contain more route sections depending on the number of set waypoints. Sections act as a route leg that break a route into several logical parts.
Waypoints are coordinates that can be set by the user to determine more sections or the shape the route (which can be useful if you want to make sure you cross a river with a ferry, for example).
Note that the online RoutingEngine
supports only a limited number of waypoints of around 200 waypoints at most.
There can be two types of waypoints:
-
STOPOVER
: The default waypoint type. It is guaranteed that this point will be passed, therefore it appears in the list of maneuver instructions, and splits the route into separate route sections. -
PASS_THROUGH
: May not appear in the maneuver instructions list and is rather treated as a hint to shape the route, for example, as a result of a touch input. This type will not split the route into separate sections.
When creating a new Waypoint
object, the STOPOVER
type is set by default - and this must be the type used for the first and the last waypoint. With just two waypoints acting as the start and destination, a route might look like below:
One route section between starting point and destination.
The RoutingEngine
can handle multiple waypoints. The underlying algorithm will try to find the best path to connect all waypoints while respecting the order of the provided List
- as well as the WaypointType
. Each STOPOVER
-waypoint is passed between the starting location and the destination, which are the first and last item of the waypoint list respectively.
Waypoint waypoint1 = new Waypoint(createRandomGeoCoordinatesInViewport());
Waypoint waypoint2 = new Waypoint(createRandomGeoCoordinatesInViewport());
List<Waypoint> waypoints = new ArrayList<>(Arrays.asList(new Waypoint(startGeoCoordinates),
waypoint1, waypoint2, new Waypoint(destinationGeoCoordinates)));
routingEngine.calculateRoute(
waypoints,
new CarOptions(),
new CalculateRouteCallback() {
@Override
public void onRouteCalculated(@Nullable RoutingError routingError, @Nullable List<Route> routes) {
if (routingError == null) {
Route route = routes.get(0);
showRouteDetails(route);
showRouteOnMap(route);
logRouteViolations(route);
} else {
showDialog("Error while calculating a route:", routingError.toString());
}
}
});
By adding two additional STOPOVER
-waypoints to the route using the code snippet above, we now have three route sections between the starting point and the destination as seen in the illustration below.
Note
The waypoints list order defines the order in which they are going to be passed along the route.
Illustration: Adding two additional waypoints.
Additional information on the route - such as the estimated time it takes to travel to the destination and the total length of the route in meters - can be retrieved from the Route
object as shown below:
long estimatedTravelTimeInSeconds = route.getDuration().getSeconds();
int lengthInMeters = route.getLengthInMeters();
Travel time and length are also available for each Section
. Without additional STOPOVER
-waypoints, the route will contain only one Section
. If additional STOPOVER
-waypoints are provided, the route is separated into several route sections between each waypoint, as well as from the starting point to the first waypoint and from the last waypoint to the destination.
Note
By default, an additional waypoint splits a route into separate sections and forces the route to pass this point and to generate a maneuver instruction for it.
Each Section
contains the shape of the route in form of a GeoPolyline
- represented as an array of coordinates where the first coordinate marks the starting point and the last one the destination.
This can be useful to visualize the route on the map by using, for example, map polylines in a different color for each Section
. However, you can also get the polyline directly from the Route
object. Below is a code snippet that shows how this could be implemented by using a MapPolyline
that is drawn between each waypoint including the starting point and the destination:
GeoPolyline routeGeoPolyline = route.getGeometry();
float widthInPixels = 20;
MapPolyline routeMapPolyline = new MapPolyline(routeGeoPolyline,
widthInPixels,
Color.valueOf(0, 0.56f, 0.54f, 0.63f));
mapView.getMapScene().addMapPolyline(routeMapPolyline);
The first screenshot below shows a route without additional waypoints - and therefore only one route section. Starting point and destination are indicated by green-circled map marker objects. Note that the code for drawing the circled objects is not shown here, but can be seen from the example's source code, if you are interested.
Screenshot: Showing a route on the map.
The second screenshot shows the same route as above, but with two additional STOPOVER
-waypoints, indicated by red-circled map marker objects. The route therefore, contains three route sections.
Screenshot: Showing a route with two additional waypoints.
Zoom to the Route
For some use cases, it may be useful to zoom to the calculated route. The camera class provides a convenient method to adjust the viewport so that a route fits in:
GeoBox routeGeoBox = route.getBoundingBox();
camera.lookAt(routeGeoBox, new GeoOrientationUpdate(null, null));
Here we use the enclosing bounding box of the route object. This can be used to instantly update the camera: Zoom level and target point of the camera will be changed, so that the given bounding rectangle fits exactly into the viewport. Additionally, we can specify an orientation to specify more camera parameters - here we keep the default values. Note that calling lookAt()
will instantly change the view.
For most use cases, a better user experience is to zoom to the route with an animation. Below you can see an example that zooms to a GeoBox
plus an additional padding of 50 pixels:
private void animateToRoute(Route route) {
double bearing = 0;
double tilt = 0;
Point2D origin = new Point2D(50, 50);
Size2D sizeInPixels = new Size2D(mapView.getWidth() - 100, mapView.getHeight() - 100);
Rectangle2D mapViewport = new Rectangle2D(origin, sizeInPixels);
MapCameraUpdate update = MapCameraUpdateFactory.lookAt(
route.getBoundingBox(),
new GeoOrientationUpdate(bearing, tilt),
mapViewport);
MapCameraAnimation animation =
MapCameraAnimationFactory.createAnimation(update, Duration.ofMillis(3000), EasingFunction.IN_CUBIC);
mapView.getCamera().startAnimation(animation);
}
The CameraKeyframeTracks
example app shows how this can look like.
Get Maneuver Instructions
Each Section
contains the maneuver instructions a user may need to follow to reach the destination. For each turn, a Maneuver
object contains an action and the location where the maneuver must be taken. The action may indicate actions like "depart" or directions such as "turn left".
List<Section> sections = route.getSections();
for (Section section : sections) {
logManeuverInstructions(section);
}
And here is the code to access the maneuver instructions per section:
private void logManeuverInstructions(Section section) {
Log.d(TAG, "Log maneuver instructions per route section:");
List<Maneuver> maneuverInstructions = section.getManeuvers();
for (Maneuver maneuverInstruction : maneuverInstructions) {
ManeuverAction maneuverAction = maneuverInstruction.getAction();
GeoCoordinates maneuverLocation = maneuverInstruction.getCoordinates();
String maneuverInfo = maneuverInstruction.getText()
+ ", Action: " + maneuverAction.name()
+ ", Location: " + maneuverLocation.toString();
Log.d(TAG, maneuverInfo);
}
}
This may be useful to easily build maneuver instructions lists describing the whole route in written form. For example, the ManeuverAction
enum can be used to build your own unique routing experience.
In the API Reference you can find an overview of the available maneuver actions.
Note
Note that the Maneuver
instruction text (maneuverInstruction.getText()
) is empty during navigation when it is taken from Navigator
or VisualNavigator
. It only contains localized instructions when taken from a Route
instance. The ManeuverAction
enum is supposed to be used to show a visual indicator during navigation, and textual instructions fit more into a list to preview maneuvers before starting a trip.
In opposition, maneuverInstruction.getRoadTexts()
, maneuverInstruction.getNextRoadTexts()
and maneuverInstruction.getExitSignTexts()
are meant to be shown as part of turn-by-turn maneuvers during navigation, so they are only non-empty when the Maneuver
is taken from Navigator
or VisualNavigator
. If taken from a Route
instance, these attributes are always empty.
Find Traffic Along a Route
You can get the overall time you are stuck in a traffic jam with:
long estimatedTrafficDelayInSeconds = route.getTrafficDelay().getSeconds();
More granular information about the traffic situation is available for the individual sections of a route: In addition to maneuvers (see above), each Section
of a Route
contains information of the traffic flow situation at the time when the route was calculated.
Each Section
can contain a various amount of TrafficSpeed
instances. These are valid along the Span
until the next Span
. Each Span
geometry is represented by a polyline that is part of the full route's polyline shape.
The following code snippet shows how to get a TrafficSpeed
element of the first Span
of a Section
:
Section firstSection = route.getSections().get(0);
TrafficSpeed firstTrafficSpeed = firstSection.getSpans().get(0).getTrafficSpeed();
TrafficSpeed
contains the baseSpeedInMetersPerSecond
, which is the expected default travel speed. Note that this may not be the same as the current speed limit on a road - as a bad road condition may justify a slower travel speed. In addition, you can get the estimated actual travel speed based on the current traffic conditions with trafficSpeedInMetersPerSecond
.
Similar to the color encoding used for the traffic flow layer, you can indicate the traffic along a route using a jamFactor
that has a range from 0 (no traffic) to 10 (road is blocked). See the Traffic section for more details on the traffic features of the HERE SDK.
An example how this value can be mapped to a suitable color is shown below:
Illustration: Traffic jam factors.
Usually, the jamFactor
can be interpreted like this:
- 0 <=
jamFactor
< 4: No or light traffic. - 4 <=
jamFactor
< 8: Moderate or slow traffic. - 8 <=
jamFactor
< 10: Severe traffic. -
jamFactor
= 10: No traffic, ie. the road is blocked.
Note that the jamFactor
indicating TrafficSpeed
is calculated linear from the ratio of trafficSpeedInMetersPerSecond
/ baseSpeedInMetersPerSecond
- without taking road types and other parameters into account. Therefore, the provided jamFactor
does not necessarily match exactly the traffic flow visualization on the map view (if enabled).
If you want to visualize the traffic along a route, consider to render multiple colored MapPolyline
objects for each span of a section:
-
In addition, you can query traffic incidents along the route with the TrafficEngine
. For this, you need to create a GeoCorridor
out from the coordinates of a Route
. Make sure to also specify a corridor radius by setting halfWidthInMeters
. Note that the GeoCorridor
is limited in length and width. Check the traffic example app to see how to use the TrafficEngine
. Check also the Traffic section in this guide.
-
If you are only interested in basic traffic incident information along the route, you can get a summary of the traffic situation directly from the Route
instance - per Section
, by calling Section.getTrafficIncidents()
. The resulting TrafficIncidentOnRoute
object contains a small subset of the data that is available with the TrafficEngine
, but it can be useful to give a first overview.
Note
You can refresh the traffic information of the route by refreshing the route via refreshRoute()
. See the section below. Alternatively, during guidance consider to use the DynamicRoutingEngine
.
Find Upcoming Speed Limits and More
The Route
object exposes detailed information along a Route
to know upcoming speed limits, street attributes and road names, dynamic traffic info and much more.
Take a look at the following attributes: Span.sectionPolylineOffset
, Span.dynamicSpeedInfo
, Span.streetAttributes
, Span.carAttributes
, Span.truckAttributes
, Span.scooterAttributes
, Span.walkAttributes
, Span.durationInSeconds
, Span.streetNames
, Span.routeNumbers
, Span.speedLimitInMetersPerSecond
, Span.consumptionInKilowattHours
, Span.functionalRoadClass
, Span.duration
, Span.baseDuration
. Consult the API Reference for a full list of attributes.
Each attribute is given per span and it is valid for the entire length of a span. Sometimes you will also find segment IDs that indicate a portion of the road network between two intersections. A Span
is a route-related concept - it is a portion of the route which has the same attributes. There can be multiple spans on the same segment and each segment usually has a start offset and an end offset.
A Span
defines the smallest part of a route segment and its curvature is exposed as a list of GeoCoordinates
.
Get Toll Costs Along a Route
You can get possible toll costs along the individual sections of a route.
Note
This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.
The RouteOptions.enableTolls
flag must be set to get toll costs. It is set to false
by default. When this flag is enabled, toll data is requested for toll applicable transport modes as defined in the API Reference.
Get toll costs via Section.getTolls()
which provides a PaymentMethod
, TollFare
& Toll
information.
During navigation - while following a route - you can use a RoadAttributesListener
that informs on new road attributes including isTollway
to know if the current road may require to pay a toll.
Avoid Road Features
Use AvoidanceOptions
to exclude tunnels, highways, emission zones, areas, ferries, toll costs and other road features, like harsh turns. You can pass a list of RoadFeatures
, ZoneCategory
, GeoBox
, CountryCode
elements and more.
RoadFeatures
contains road specific features like tunnels or toll roads. For example, to exclude all highways from your journey, add CONTROLLED_ACCESS_HIGHWAY
to the list of features.
AvoidanceOptions
can be set together with other route options including localization and unit options to the options for the desired transport mode. For example, for car, use CarOptions
, for trucks, TruckOptions
and so on. These options are then read when calculating a route and in case of AvoidanceOptions
, the engine will try to avoid the listed features.
Refresh Routes
The traffic flow information contained in a Route
object is valid for the time when the route was calculated, see above. If you want to update this information at any later point in time, you can refresh the route.
It is also possible to refresh the route options for a route:
RefreshRouteOptions refreshRouteOptions = new RefreshRouteOptions(taxiOptions);
routingEngine.refreshRoute(route.getRouteHandle(), mapMatchedWaypoint, refreshRouteOptions, new CalculateRouteCallback() {
@Override
public void onRouteCalculated(@Nullable RoutingError routingError, @Nullable List<Route> list) {
if (routingError == null) {
Route newRoute = list.get(0);
} else {
}
}
});
For this you need to know the RouteHandle
, which must be requested via RouteOptions.enableRouteHandle()
before the route was calculated.
In addition, refreshing a route can be useful to convert the route options from one transport type to another or to update specific options. If the conversion is not possible - for example, when a pedestrian route is converted to a truck route, then a routingError
indicates this.
You can also shorten the route, by specifying a new starting point. The new starting point must be very close to the original route as no new route is calculated. If the new starting point is too far away, then a routingError
occurs.
Note that refreshing a route is not enough when a driver deviates from a route during an ongoing turn-by-turn navigation - as the detour part needs a new route calculation. In such a case, it may be more useful to recalculate the whole route by setting a new starting point - or to use the returnToRoute()
method that allows to keep the originally chosen route alternative.
During turn-by-turn navigation you can refresh a route in order to get the latest traffic delay updates ahead. Before the refreshed route can be set to the Navigator
, the last location on the route needs to be set as new starting point. However, this can lead to unexpected results when the driver has already advanced while the refresh operation is ongoing. Either way, if you just want to update the ETA - and the new starting point lies on the existing route, you do not necessarily need to set the new route: Instead, you can just use the updated ETA including traffic delay time - as the rest of the route ahead remains unchanged. Setting a new route during guidance effectively starts a new navigation session.
As an alternative, consider to use the DynamicRoutingEngine
that requires to set the last location and the current section index: This information will be used when the next dynamicRoutingEngineOptions.pollInterval
is reached. As a trade-off, this does not lead to an immediate update and the route shape may change if a better route is found to bypass current traffic obstacles. Again, as with refreshRoute()
you need to decide if you want to set the new route or not.
Note
Refreshing routes is not supported for the OfflineRoutingEngine
- as quering the current traffic situation requires an online connection.
Return to a Route
The RoutingEngine
allows to refresh an existing route (see above) based on the current traffic situation. The result may be a new route that is faster than the previous one. However, the new startingPoint
must be very close to the original route.
If you need to handle a case where the startingPoint
is farther away from the route, consider to use the returnToRoute()
feature of the RoutingEngine
. For example, a driver may decide to take a detour due to the local traffic situation. Calling returnToRoute()
will also result in a new route, but it will try to resemble as much as possible from the original route without a costly route recalculation - if possible.
- Stopover waypoints are guaranteed to be passed by.
- Pass-through waypoints are only meant to shape the route, so there is no guarantee that the new route will honor or discard them.
- The current traffic situation is taken into account and may reshape the route.
Note that turn-by-turn navigation is only available for the Navigate Edition.
Note
The returnToRoute()
method is also available for the OfflineRoutingEngine
that works offline on cached or downloaded map data. However, it does not take the current traffic situation into account.
Import Routes From Other Services
You can import routes from other APIs and/or vendors via one of the various overloaded routingEngine.importRoute()
methods. Note that this is not a 1:1 import feature, but rather a reconstruction.
A new Route
object can be created from:
- A list of
GeoCoordinates
and RouteOptions
. This can be useful, when the route should be imported from a different vendor. - A
RouteHandle
. This can be useful to import a route from other HERE services. A possible use case can be to create a route on the HERE WeGo website or another web page that uses the HERE REST APIs and then transfer it to a mobile device to start a trip. Note that a map update on backend side or other changes in the real world can lead to an invalid handle. Therefore, it is recommended to use the handle only for a few hours. Although the RouteHandle
encodes certain information, it requires an online connection to get the full route data from backend.
Any AvoidanceOptions
that are applied may be discarded and reported as violations via the route's Section.getSectionNotices()
. For example, if you request to avoid highways, but the provided coordinates match to a highway road, then the resulting route will still match the highway, but a notice is added to indicate that the desired avoidance option is violated.
In general, be aware that importing a route may not always reproduce exactly the same route as the original one. Below we look more into the details.
Import Routes from a List of Geographic Coordinates
To import a route from a list of GeoCoordinates
with RouteOptions
, a list of GeoCoordinates
is needed that define the route shape. Such coordinates need to be very close to each other, or the calculation will fail. Such a list of coordinates can be extracted from a route calculated by a different vendor or it can be extracted from a GPX trace, for example.
List<Location> locations = Arrays.asList (new Location(new GeoCoordinates(52.518032,13.420632)), new Location(new GeoCoordinates(52.51772,13.42038)),
new Location(new GeoCoordinates(52.51764,13.42062)), new Location(new GeoCoordinates(52.51754,13.42093)),
new Location(new GeoCoordinates(52.51735,13.42155)), new Location(new GeoCoordinates(52.51719,13.42209)),
new Location(new GeoCoordinates(52.51707,13.42248)), new Location(new GeoCoordinates(52.51695,13.42285)),
new Location(new GeoCoordinates(52.5168, 13.42331)), new Location(new GeoCoordinates(52.51661,13.42387)),
new Location(new GeoCoordinates(52.51648,13.42429)), new Location(new GeoCoordinates(52.51618,13.42513)),
new Location(new GeoCoordinates(52.5161,13.42537)), new Location(new GeoCoordinates(52.51543,13.42475)),
new Location(new GeoCoordinates(52.51514,13.42449)), new Location(new GeoCoordinates(52.515001,13.424374)));
routingEngine.importRoute(locations, new CarOptions(), new CalculateRouteCallback() {
@Override
public void onRouteCalculated(@Nullable RoutingError routingError, @Nullable List<Route> list) {
if (routingError == null) {
Route newRoute = list.get(0);
} else {
}
}
});
For this option, you can select the overload of the importRoute()
method that matches your desired transport type.
When importing a route from a list of GeoCoordinates
and RouteOptions
then the RoutingEngine
will create the route shape as closely as possible from the provided geographic coordinates.
The list of coordinates is not unlimited: Please refer to the API Reference for the maximum number of supported items.
For best results use 1Hz GPS data, or points that have a spacing of a few meters. Very sparse data may result in an error.
Note: This is a beta release of this feature.
Import Routes from a RouteHandle
Below we take a look into the RouteHandle
option. With the RouteHandle(String handle)
constructor you can create a RouteHandle
from a given string handle. Such a string can be provided from other backend sources such as one of the available HERE REST APIs. Note that the string is only valid for a couple of hours.
Below you can find an example REST API call to create a route with a route handle string (replace YOUR_API_KEY
with the actual key you have in use):
https://router.hereapi.com/v8/routes?apikey=-YOUR_API_KEY&origin=52.524465%2C13.382334&destination=52.525301%2C13.399844&return=polyline%2Csummary%2Cactions%2Cinstructions%2CrouteHandle&transportMode=car
You can copy the route handle string from the JSON response and use it with the HERE SDK like so:
routingEngine.importRoute(new RouteHandle("routeHandleStringFromBackend"),
new RefreshRouteOptions(TransportMode.CAR),
new CalculateRouteCallback() {
@Override
public void onRouteCalculated(@Nullable RoutingError routingError, @Nullable List<Route> list) {
if (routingError == null) {
Route newRoute = list.get(0);
} else {
}
}
});
The RouteHandle
string identifies an already calculated route. Once imported successfully, a new Route
object is created and provided as part of the CalculateRouteCallback
for further use with the HERE SDK.
Note: This is a beta release of this feature.
Import Routes Offline
The HERE SDK does not support importing routes offline - at least not like shown above via a RouteHandle
or by directly passing in a list of GeoCoordinates
. This is only possible with the RoutingEngine
that requires an online connection.
However, there is a workaround possible: By inserting an unlimited number of Waypoint
items into the OfflineRoutingEngine
a route can be calculated offline with the specified stopover waypoints to shape the route as close as possible as the original route. Note that the RoutingEngine
supports only a limited number of waypoints of around 200 waypoints at most. When using the OfflineRoutingEngine
there is no such limitation, but there may be performance trade-offs for longer routes. Therefore, it is recommended to pass only a subset of all route coordinates as waypoints - for example, filtered by a distance threshold.
Read on in the next chapter to learn about the OfflineRoutingEngine
. Additional waypoints can be set in the same way as already shown above for the online RoutingEngine
.
Offline Routing
In addition to the RoutingEngine
, there is also an equivalent for offline use cases available: The OfflineRoutingEngine
. It can be constructed in the same way as its online counterpart we already showed above:
private RoutingInterface routingEngine;
private RoutingEngine onlineRoutingEngine;
private OfflineRoutingEngine offlineRoutingEngine;
...
try {
onlineRoutingEngine = new RoutingEngine();
} catch (InstantiationErrorException e) {
throw new RuntimeException("Initialization of RoutingEngine failed: " + e.error.name());
}
try {
offlineRoutingEngine = new OfflineRoutingEngine();
} catch (InstantiationErrorException e) {
throw new RuntimeException("Initialization of OfflineRoutingEngine failed: " + e.error.name());
}
Note
Transit routes (via TransitRoutingEngine
), Taxi (TaxiOptions
) and EV routes (EVCarOptions
and EVTruckOptions
) are not yet supported and only work online. The OfflineRouteEngine
will fail with RoutingError.INVALID_PARAMETER
in case of unsupported transport modes.
The OfflineRoutingEngine
provides the same interfaces as the RoutingEngine
, but the results may slightly differ as the results are taken from already downloaded or cached map data instead of initiating a new request to a HERE backend service.
This way the data may be, for example, older compared to the data you may receive when using the RoutingEngine
. On the other hand, this class provides results faster - as no online connection is necessary.
However, the resulting routes contain only an empty list of maneuvers. If you need to get maneuvers during guidance, you can get them directly from the Navigator
or VisualNavigator
via the provided nextManeuverIndex
. This is shown in the Navigation section.
Note
You can only calculate routes on already cached or preloaded offline maps data. When you use only cached map data, it may happen that not all tiles are loaded for the lower zoom levels. In that case, no route can be found until also the lower zoom levels are loaded - even if you see the map. With offline maps this cannot happen and the required map data is guaranteed to be available for the downloaded region. Therefore, it is recommended to not rely on cached map data.
All available interfaces of the OfflineRoutingEngine
are also available in the RoutingEngine
and both engines adopt the same interface. This makes it easy to switch between both engine instances as we will show below.
Note
To get a quick overview of how all of this works, you can take a look at the offline RoutingExample class. It contains all code snippets shown below and it is part of the RoutingHybrid example app you can find on GitHub.
Below we show how to switch between OfflineRoutingEngine
and RoutingEngine
. For example, when you are on the go, it can happen that your connection is temporarily lost. In such a case it makes sense to calculate routes on the already cached or downloaded map data with the OfflineRoutingEngine
.
To do so, first you need to check if the device has lost its connectivity. As a second step you can use the preferred engine:
private void setRoutingEngine() {
if (isDeviceConnected()) {
routingEngine = onlineRoutingEngine;
} else {
routingEngine = offlineRoutingEngine;
}
}
Now, you can execute the same code on the current routingEngine
instance, as shown in the previous sections above.
Note
If the device is offline, the online variant will not find routes and will report an error. Vice versa, when the device is online, but no cached or preloaded map data is available for the area you want to use, the offline variant will report an error as well.
Note that the code for isDeviceConnected()
to check if the device is online or not is left out here. You may use a 3rd party API for this or try to make an actual connection - and when that fails, you can switch to the OfflineRoutingEngine
- or the other way round: You can try offline routing first to provide a fast experience for the user, but when no map data is available, you can try online.
Note
You can find the RoutingHybrid example app on GitHub.
Optimize the Waypoint Order
The OfflineEngine
(see above) also allows offline waypoint sequencing to support the travelling salesman use case. Note that the feature is not yet supported for the online RoutingEngine
.
Multiple stopover Waypoint
items along a Route
can be ordered automatically by setting the RouteOptions.optimizeWaypointsOrder
: If set to true
, the OfflineRoutingEngine
will try to optimize the waypoints order to reach the destination faster or to make the route shorter - while ensuring that all set waypoints of type stopover
are reached.
The specified OptimizationMode
determines if the reordering results in a faster or shorter route.
At least 5 or more waypoints (including starting point and destination) need to be set in order to see an effect on the route calculation. If needed, the reshuffled waypoints can be identified by comparing the originalCoordinates
of each RoutePlace
with the user-defined coordinates. RoutePlace
objects are provided for each Section
of a Route
object as each stopover splits the route into sections. During navigation the MilestoneStatus
event informs if a user-defined waypoint has been reached.
Illustration: A route with and without waypoint sequencing.
Note that this is a beta release of this feature.
Show Reachable Area
With isoline routing you can generate polygons to represent the area of reach from a given point based on time, distance or energy consumption: The polygon will encompass all destinations that can be reached in a specific amount of time, a maximum travel distance, or even the charge level available at an electric vehicle.
Note
Isoline routing considers real-time and historical traffic in its calculations.
Some examples of how this could be useful:
- Users can find restaurants within a 2 km walking distance from their current location.
- Users can search for hotels based on the distance to sights, for example, to find hotels within a 20 minute drive to major attractions - such as Disney World and Universal Studios in Orlando, Florida USA.
Below we show a consumption based Isoline
example for an electric vehicle scenario, where the driver wants to know which points are reachable within the provided limit of 400 Wh: So, the goal is to consume 400 Wh or less - and the question is: What can the driver reach within this energy limit?
Note
Electric vehicles have a limited reachable range based on their current battery charge and factors affecting the rate of energy consumed, such as road slope or auxiliary power usage. Therefore, it is useful to visualize the appropriate range to avoid running out of energy before reaching a charging point. Since vehicles have unique consumption parameters, they are to be specified in the request for an accurate range to be calculated. For more details, see the electric vehicle section below.
The result will be a GeoPolygon
shape that you can show on the map to provide the driver a visual orientation:
List<Integer> rangeValues = Collections.singletonList(400);
IsolineOptions.Calculation calculationOptions =
new IsolineOptions.Calculation(IsolineRangeType.CONSUMPTION_IN_WATT_HOURS, rangeValues, IsolineCalculationMode.BALANCED);
IsolineOptions isolineOptions = new IsolineOptions(calculationOptions, getEVCarOptions());
routingEngine.calculateIsoline(new Waypoint(startGeoCoordinates), isolineOptions, new CalculateIsolineCallback() {
@Override
public void onIsolineCalculated(RoutingError routingError, List<Isoline> list) {
if (routingError != null) {
showDialog("Error while calculating reachable area:", routingError.toString());
return;
}
Isoline isoline = list.get(0);
for (GeoPolygon geoPolygon : isoline.getPolygons()) {
Color fillColor = Color.valueOf(0, 0.56f, 0.54f, 0.5f);
MapPolygon mapPolygon = new MapPolygon(geoPolygon, fillColor);
mapView.getMapScene().addMapPolygon(mapPolygon);
mapPolygons.add(mapPolygon);
}
}
});
This finds the area that an electric vehicle can reach by consuming 400 Wh or less, while trying to take the fastest possible route into any possible straight direction from start.
Why fastest? This depends on the route's optimization mode (we have shown in earlier sections above) - of course, you can specify any mode. Note that each isoline needs exactly one center point from where a journey may start.
Since we are interested in the energy consumption, we also provided EVCarOptions
. These options must include battery specifications as shown in the electric vehicle routing section below. If you provide a time or distance limit instead as range type, you can provide the usual route options as shown earlier.
The IsolineRangeType
defines the type of the provide range value. Here we use 400. You can provide multiple values - and as a result you would then get multiple Isoline
objects - one for each provided range value.
On the other hand, each Isoline
object can contain multiple polygons for special cases, such as when the area of reach includes an island. Such areas are provided as separate polygons.
The shape of the resulting polygon can be defined by the maxPoints
parameter. It determines the number of vertices of the GeoPolygon
. Note that this parameter does not influence the actual calculation of the polygon, but just its apearance.
Screenshot: Showing the area of reach for the given limit.
The screenshot shows the center location of the polygon, indicated by a big green circle. It also shows a possible route beyond this area with two additional found charging stations along the route. In the next section you can find how to calculate routes for electric vehicles.
Note
You can find the above code snippet as part of the EVRouting
example app on GitHub.
Get Routes for Electric Vehicles
Electric vehicle (EV) usage and sales continue growing around the world. How can HERE help to provide the best routes for electric vehicles?
-
HERE EV Routing delivers optimized routes for EVs to get from A to B, minimizing the number of charging stops and optimizing battery charge times (based on the vehicle’s consumption model). It also takes into account a number of factors when planning trips, including topography, road geometry, real-time traffic information and traffic patterns.
-
Instead of searching for charging stations along the route, HERE analyzes the charging time at every possible station and chooses the most appropriate combination that will deliver the shortest driving and charging times.
Getting EV routes is simple. Similar to getting car or truck routes, for EV routing you just need to add electric vehicle specific route options. This way you can get routes for electric vehicles in the same way as for other transport modes. Just specify EVRouteOptions
and add them to the calculateRoute()
method:
routingEngine.calculateRoute(waypoints, getEVCarOptions(), new CalculateRouteCallback() {
@Override
public void onRouteCalculated(RoutingError routingError, List<Route> list) {
if (routingError != null) {
showDialog("Error while calculating a route: ", routingError.toString());
return;
}
}
});
By default, EVRouteOptions
will not include the required parameters to ensure that a destination can be reached without running out of energy.
To ensure this, you need to set the required parameters that may add charging stations to the route - while still optimizing the result for overall travel time.
Below you can see an example how to create such options:
private EVCarOptions getEVCarOptions() {
EVCarOptions evCarOptions = new EVCarOptions();
evCarOptions.consumptionModel.ascentConsumptionInWattHoursPerMeter = 9;
evCarOptions.consumptionModel.descentRecoveryInWattHoursPerMeter = 4.3;
evCarOptions.consumptionModel.freeFlowSpeedTable = new HashMap<Integer, Double>() {{
put(0, 0.239);
put(27, 0.239);
put(60, 0.196);
put(90, 0.238);
}};
evCarOptions.routeOptions.alternatives = 0;
evCarOptions.ensureReachability = true;
evCarOptions.avoidanceOptions = new AvoidanceOptions();
evCarOptions.routeOptions.speedCapInMetersPerSecond = null;
evCarOptions.routeOptions.optimizationMode = OptimizationMode.FASTEST;
evCarOptions.batterySpecifications.connectorTypes =
new ArrayList<>(Arrays.asList(ChargingConnectorType.TESLA,
ChargingConnectorType.IEC_62196_TYPE_1_COMBO, ChargingConnectorType.IEC_62196_TYPE_2_COMBO));
evCarOptions.batterySpecifications.totalCapacityInKilowattHours = 80.0;
evCarOptions.batterySpecifications.initialChargeInKilowattHours = 10.0;
evCarOptions.batterySpecifications.targetChargeInKilowattHours = 72.0;
evCarOptions.batterySpecifications.chargingCurve = new HashMap<Double, Double>() {{
put(0.0, 239.0);
put(64.0, 111.0);
put(72.0, 1.0);
}};
return evCarOptions;
}
Here we define the EVConsumptionModel
to specify the energy consumption model of the electric vehicle. We also add BatterySpecifications
. With these options, additional charging stations may be inserted into the route as additional stopovers - which means that the route will be split into more sections depending on the number of inserted charging stations.
Note
If you want to include such required charging stations, it is also mandatory to use OptimizationMode.FASTEST
. You also need to set ensureReachability
to true. When ensureReachability
is activated, the route may be adjusted so that required charging stations are along the resulting path and the required charging stations are added as WayPoint
items to the route
.
All options can influence the time it takes to calculate a route for electric vehicles. Most importantly, a large battery capacity - as set with totalCapacityInKilowattHours
- can decrease the need for charging stops - as well as a fully loaded battery when starting the trip - see initialChargeInKilowattHours
: A relatively low value means that the route must include charging stations near the beginning. Otherwise, the route calculation may even fail.
Currently, the engine will only include charging stations that are in service. Charging stations that our out-of-service or in maintenance are not considered. However, due to the dynamic situation at charging stations, the engine does not consider if a station is currently occupied or reserved. So, in worst case, it can happen that you arrive at a station and it is currently being used to charge another car.
Note that we also specify the available battery connector types, so that charging stations that do not provide a compatible connector to charge the car will be excluded.
Note
Usually, you can take the consumption and battery information from the car itself or consult the manual or your car manufacturer directly. Note that not all information may be available to you and some information may be only exclusively known by the manufacturer. Either way, the route calculation process will take the provided specifications into account and missing values will be filled with suitable default values.
Especially for longer journeys with electric vehicles, it is important to plan for charging stops along the way. After all, charging stations are much less common than gas stations. With the above options, the RoutingEngine
tries to find the fastest route, i.e., one with the lowest overall time consumed to reach the destination, while ensuring that the vehicle does not run out of energy along the way.
The result of the calculation is a route optimized for electric vehicles - instead of just adding any charging stations found along the way - as we have shown in the Search Along a Route section.
Once the route
is calculated, you can gather more useful information. The code snippet shown below will log the estimated energy consumption per Section
and list the actions you need to take in order to charge the battery - if needed:
int additionalSectionCount = route.getSections().size() - 1;
if (additionalSectionCount > 0) {
Log.d("EVDetails", "Number of required stops at charging stations: " + additionalSectionCount);
} else {
Log.d("EVDetails","Based on the provided options, the destination can be reached without a stop at a charging station.");
}
int sectionIndex = 0;
List<Section> sections = route.getSections();
for (Section section : sections) {
EVDetails evDetails = section.getEvDetails();
if (evDetails == null) {
return;
}
Log.d("EVDetails", "Estimated net energy consumption in kWh for this section: " + evDetails.consumptionInKilowattHour);
for (PostAction postAction : section.getPostActions()) {
switch (postAction.action) {
case CHARGING_SETUP:
Log.d("EVDetails", "At the end of this section you need to setup charging for " + postAction.duration.getSeconds() + " s.");
break;
case CHARGING:
Log.d("EVDetails", "At the end of this section you need to charge for " + postAction.duration.getSeconds() + " s.");
break;
case WAIT:
Log.d("EVDetails", "At the end of this section you need to wait for " + postAction.duration.getSeconds() + " s.");
break;
default: throw new RuntimeException("Unknown post action type.");
}
}
Log.d("EVDetails", "Section " + sectionIndex + ": Estimated battery charge in kWh when leaving the departure place: " + section.getDeparturePlace().chargeInKilowattHours);
Log.d("EVDetails", "Section " + sectionIndex + ": Estimated battery charge in kWh when leaving the arrival place: " + section.getArrivalPlace().chargeInKilowattHours);
ChargingStation depStation = section.getDeparturePlace().chargingStation;
if (depStation != null && depStation.id != null && !chargingStationsIDs.contains(depStation.id)) {
Log.d("EVDetails", "Section " + sectionIndex + ", name of charging station: " + depStation.name);
chargingStationsIDs.add(depStation.id);
addCircleMapMarker(section.getDeparturePlace().mapMatchedCoordinates, R.drawable.required_charging);
}
ChargingStation arrStation = section.getDeparturePlace().chargingStation;
if (arrStation != null && arrStation.id != null && !chargingStationsIDs.contains(arrStation.id)) {
Log.d("EVDetails", "Section " + sectionIndex + ", name of charging station: " + arrStation.name);
chargingStationsIDs.add(arrStation.id);
addCircleMapMarker(section.getArrivalPlace().mapMatchedCoordinates, R.drawable.required_charging);
}
sectionIndex += 1;
}
Note that postAction.duration.getSeconds()
provides the estimated time it takes to charge the battery. This time is included in the overall route calculation and the estimated time of arrival (ETA).
Below is a screenshot of how a resulting route may look.
Screenshot: Showing a route for electric vehicles.
Here you can see that the route required two stops at a charging station - indicated by red markers. The route contains three sections as each charging station splits the route - when inserting additional waypoints.
The first section includes a post action which describes the charging stop. It contains the information on the expected arrival charge among other information.
Unless specified otherwise, the energy consumption is assumed to be in Wh.
Define the Consumption Model
The following parameters define a consumption model to get more accurate results for electric vehicles:
- ascentConsumptionInWattHoursPerMeter: Rate of energy consumed per meter rise in elevation.
- descentRecoveryInWattHoursPerMeter: Rate of energy recovered per meter fall in elevation.
- freeFlowSpeedTable: Function curve specifying consumption rate at a given free flow speed on a flat stretch of road.
- trafficSpeedTable: Function curve specifying consumption rate at a given speed under traffic conditions on a flat stretch of road.
- auxiliaryConsumptionInWattHoursPerSecond: Rate of energy consumed by the vehicle's auxiliary systems (e.g., air conditioning, lights) per second of travel.
A consumption speed table defines the energy consumption rate when the vehicle travels on a straight road without elevation change at a given speed in km/h. It represents a piecewise linear function.
Here is an example of a free flow speed list. On the left you see the speed and on the right, consumption:
- 0: 0.239
- 27: 0.239
- 45: 0.259
- 60: 0.196
- 75: 0.207
- 90: 0.238
- 100: 0.26
- 110: 0.296
- 120: 0.337
- 130: 0.351
In a graph it will look like this:
Screenshot: An example for a consumption speed graph.
You can specify two different consumption speed tables - free flow speed table and traffic speed tables:
- Free flow speed: Describes the energy consumption when travelling at constant speed.
- Traffic speed: Describes the energy consumption when travelling under heavy traffic conditions, for example, when the vehicle is expected to often change the travel speed at a given average speed.
If a trafficSpeedTable
is not provided then only the freeFlowSpeedTable
is used for calculating speed-related energy consumption.
Note
You can find an EVRouting
example app on GitHub.