HERE SDK for Android (Premium Edition)
SDK for Android Developer's Guide

Calculating Isoline routing requests

An isoline describes potential routes user can take and provides a polygon indicating the maximum reach in all directions around the given start position by time or distance.

An isoline may consist of several isolated components. This support use cases where the reachable area is disconnected by ferry links.

All islands are returned as separate polygons (components). Ferry links between these polygons are also returned as separate polyline geometries (connections).

The range of reachable using ferries can be displayed as multiple components (with or without connections) or even as a single component.

Requesting a distance-based isoline

To calculate a distance-based isoline, specify distance as range type. The range will then be specified in meters. The mode can be either shortest or fastest. A different area can be reached by always driving the fastest possible route, then always driving the shortest possible route. The request below will calculate a 30km isoline around the center of Berlin with the shortest mode. This answers the question: what area can I reach by traveling no more than 30km?

IsolineRouter isolineRouter = new IsolineRouter();
isolineRouter.setConnectivity(IsolineRouter.Connectivity.ONLINE);

IsolinePlan isolinePlan = new IsolinePlan();
isolinePlan.setStart(new RouteWaypoint(new GeoCoordinate(52.4927, 13.4006)));

ArrayList<Integer> ranges = new ArrayList<>();
ranges.add(30000); // range in meters
isolinePlan.setRanges(ranges);

RouteOptions routeOptions = new RouteOptions();
routeOptions.setTransportMode(RouteOptions.TransportMode.CAR);
routeOptions.setRouteType(RouteOptions.Type.SHORTEST);

isolineRouter.calculateIsoline(isolinePlan, new IsolineRouter.Listener() {
  @Override public void onCalculateIsolineFinished(List<Isoline> response,
      IsolineError error) {
    if (error != IsolineError.NONE) {

    }
  }
});
Figure 1. Example isoline representing a travel distance of 30km from the center of Berlin.

Drivers normally want to drive the fastest possible route. It is possible to calculate an isoline which simulates this behavior while limiting it to a given distance. The request below will calculate a 30km isoline around the center of Berlin with the fastest mode. This answers the question: what area can I reach by traveling no more than 30km while driving the fastest possible route?

IsolineRouter isolineRouter = new IsolineRouter();
isolineRouter.setConnectivity(IsolineRouter.Connectivity.ONLINE);

IsolinePlan isolinePlan = new IsolinePlan();
isolinePlan.setStart(new RouteWaypoint(new GeoCoordinate(52.4927, 13.4006)));

ArrayList<Integer> ranges = new ArrayList<>();
ranges.add(30000); // range in meters
isolinePlan.setRanges(ranges);

RouteOptions routeOptions = new RouteOptions();
routeOptions.setTransportMode(RouteOptions.TransportMode.CAR);
routeOptions.setRouteType(RouteOptions.Type.FASTEST);

isolineRouter.calculateIsoline(isolinePlan, new IsolineRouter.Listener() {
  @Override public void onCalculateIsolineFinished(List<Isoline> response,
      IsolineError error) {
    if (error != IsolineError.NONE) {

    }
  }
});
Figure 2. Example isoline representing a travel distance of 30km from the center of Berlin while driving the fastest possible route.

Requesting a time based isoline

To calculate a time-based isoline, specify the time as range type. The range will be specified in seconds. The request below will calculate a 1-hour isoline around the center of Berlin. This answers the question: what area I can reach in one hour from a given position?

IsolineRouter isolineRouter = new IsolineRouter();
isolineRouter.setConnectivity(IsolineRouter.Connectivity.ONLINE);

IsolinePlan isolinePlan = new IsolinePlan();
isolinePlan.setStart(new RouteWaypoint(new GeoCoordinate(52.4927, 13.4006)));

ArrayList<Integer> ranges = new ArrayList<>();
ranges.add(3600); // range in seconds
isolinePlan.setRanges(ranges);
isolinePlan.setRangeType(IsolinePlan.RangeType.TIME);

isolineRouter.calculateIsoline(isolinePlan, new IsolineRouter.Listener() {
  @Override public void onCalculateIsolineFinished(List<Isoline> response,
      IsolineError error) {
    if (error != IsolineError.NONE) {

    }
  }
});
Figure 3. Example isoline representing a 1 hour travel time from the center of Berlin.

Setting the level of detail

The isoline polygon can contain a lot of points which may be a problem for visualizing it on higher zoom levels.

Below is an example of the 30km isoline calculated in the center of Berlin.

IsolineRouter isolineRouter = new IsolineRouter();
isolineRouter.setConnectivity(IsolineRouter.Connectivity.ONLINE);

IsolinePlan isolinePlan = new IsolinePlan();
isolinePlan.setStart(new RouteWaypoint(new GeoCoordinate(52.4927, 13.4006)));

ArrayList<Integer> ranges = new ArrayList<>();
ranges.add(30000); // range in meters
isolinePlan.setRanges(ranges);

IsolineOptions isolineOptions = new IsolineOptions();
isolineOptions.setIsolineQuality(IsolineOptions.IsolineQuality.BEST_QUALITY);


isolineRouter.calculateIsoline(isolinePlan, new IsolineRouter.Listener() {
  @Override public void onCalculateIsolineFinished(List<Isoline> response,
      IsolineError error) {
    if (error != IsolineError.NONE) {

    }
  }
});
Figure 4. Example of isoline with many points.

There are two ways to control the level of detail of the isoline polygon. The first one is view resolution. The view resolution allows the client to specify the level of detail needed for visualizing the polygon. It is specified in meters per pixel and reflects the client's zoom level and screen resolution. The isoline service will use this value in order to find the balanced level of detail.

Below is an example of the same isoline request, with view resolution parameter:

IsolineRouter isolineRouter = new IsolineRouter();
isolineRouter.setConnectivity(IsolineRouter.Connectivity.ONLINE);

IsolinePlan isolinePlan = new IsolinePlan();
isolinePlan.setStart(new RouteWaypoint(new GeoCoordinate(52.4927, 13.4006)));

ArrayList<Integer> ranges = new ArrayList<>();
ranges.add(30000); // range in meters
isolinePlan.setRanges(ranges);

IsolineOptions isolineOptions = new IsolineOptions();
isolineOptions.setIsolineQuality(IsolineOptions.IsolineQuality.BALANCED);


isolineRouter.calculateIsoline(isolinePlan, new IsolineRouter.Listener() {
  @Override public void onCalculateIsolineFinished(List<Isoline> response,
      IsolineError error) {
    if (error != IsolineError.NONE) {

    }
  }
});
Figure 5. Example of isoline with view resolution applied.

The second way is to set the maximum number of points allowed in the isoline. Once a number is provided in the request the service will automatically adjust the level of detail and perform shape simplification in order to fit within the limit.

Note: This option should be used if a client has some physical limitation on the number of points it is able to process. Please avoid using this option to control zoom level, use view resolution instead. View resolution and max points can be used at the same time.

Below is an example of the same isoline request, with max points parameter:

IsolineRouter isolineRouter = new IsolineRouter();
isolineRouter.setConnectivity(IsolineRouter.Connectivity.ONLINE);

IsolinePlan isolinePlan = new IsolinePlan();
isolinePlan.setStart(new RouteWaypoint(new GeoCoordinate(52.4927, 13.4006)));

ArrayList<Integer> ranges = new ArrayList<>();
ranges.add(30000); // range in meters
isolinePlan.setRanges(ranges);

IsolineOptions isolineOptions = new IsolineOptions();
isolineOptions.setIsolineQuality(IsolineOptions.IsolineQuality.BEST_PERFORMANCE);

isolineRouter.calculateIsoline(isolinePlan, new IsolineRouter.Listener() {
  @Override public void onCalculateIsolineFinished(List<Isoline> response,
      IsolineError error) {
    if (error != IsolineError.NONE) {

    }
  }
});
Figure 6. Example of isoline with max points applied.