HERE Android SDK Developer's Guide

Transit Routing

Similar to car and pedestrian routing through CoreRouter, you can perform public transport routing (otherwise known as Urban Mobility routing) through UMRouter, while specifying options through the UMRouteOptions class.

Notes and Disclaimers

Before using the Transit Routing feature, be aware of the following:

  • Transit routing is currently offered as a beta feature. APIs may change without notice.
  • Access to the Transit Routing feature is restricted. Contact a HERE representative (https://developer.here.com/contact-us?interest=mobile-sdk#contact-sales) for more information and to request for access.
  • To use this feature, your application must include the Gson library (release 2.2.4 or a compatible version) on its class path.
  • RouteManager and RouteOptions.TransportMode.PUBLIC_TRANSPORT have been deprecated as of HERE SDK v3.2 Transit routing is now handled by a set of Urban Mobility (UM) routing classes, with the main entry point being the UMRouter class.

Urban Mobility Routing Example

The following is an example of how to calculate a public transit route that connects two waypoints (start and destination):

  1. Declare a UMRouter instance.
    // Declare the variable (the UMRouter)
    UMRouter router = new UMRouter();
    
  2. Create a RoutePlan and add two GeoCoordinate waypoints.
    // Create the RoutePlan and add two waypoints
    RoutePlan plan = new RoutePlan();
    // add start point to route plan
    plan.addWaypoint(new RouteWaypoint(new GeoCoordinate(40.750488, -73.993546)));
    // add end point to route plan
    plan.addWaypoint(new RouteWaypoint(new GeoCoordinate(40.749877, -73.845853)));
    
    Note: Destinations that are too close to the starting waypoint are not supported. Use a pedestrian route calculation instead.
  3. Create a new UMRouteOptions object and set the desired options. Add the route options to RoutePlan.
    // Create the UMRouteOptions and set its options
    UMRouteOptions options = new UMRouteOptions();
    // setup walk parameters
    options.setTransitWalkMaxDistance(1000);
    options.setTransitWalkTimeMultiplier(0.75f);
    plan.setRouteOptions(options);
    
  4. Create a UMRouter.Listener instance by implementing the onCalculateRouteFinished(UMCalculateResult, ErrorCode) and onProgress(int) methods. Note that the returned object, UMCalculateResult, may contain multiple route results (UMRouteResult), each of which contains a single UMRoute.

    UMRoute can be used to create a MapRoute instance for rendering purposes.

    
     UMRouter.Listener listener = new UMRouter.Listener() {
      @Override
      public void onCalculateRouteFinished(UMCalculateResult response, ErrorCode error) {
        if (error == ErrorCode.NONE) {
          for (UMRouteResult result: response.getResults()) {
            int changesCount = result.getUMRoute().getChangesCount();
            List<Tariff> tariffs =
                result.getUMRoute().getTariffs();
      
            for (RouteSection section: result.getUMRoute().getSections()) {
              Departure departure = section.getDeparture();
              Collection<Alert> alerts = section.getAlerts();
            }
            // ...
      
            MapRoute mapRoute = new MapRoute(result.getUMRoute());
            // show mapRoute on the map
          }    
          if (response.isSubsequentRouteSupported()) {
            // UMRouter.calculateSubsequentRoute() can be used to calculate later routes
          }
        } else {
          String errorMessage = response.getErrorMessage();
          // display error
        }
      }
    
      @Override
      public void onProgress(int percentage) {
        // update progress
      }
    };
    
  5. To perform subsequent route calculations, check if the returned UMCalculateResult object supports subsequent routes, and call calculateSubsequentRoute(UMCalculateResult, SubsequentRouteType, int, UMRouter.Listener) as needed. For more information on subsequent routes, see the Subsequent Routes section in this chapter.
  6. After adding the listener class (named listener for this example), calculate the route by calling UMRouter.calculateRoute(RoutePlan, UMRouter.Listener). Note that UMRouter.Listener extends Router.Listener<List<RouteResult>, RoutingError>.
    // Calculate the route
    router.calculateRoute(routePlan, listener);
    
  7. You are required to display the source attribution, retrieved through the Route.getTransitRouteSourceAttribution() method somewhere near the route results.
  8. Geometry, line color, and other types of display information can be retrieved through TransitRouteElement objects, available through the UMRoute. You can retrieve and display ticket fare information by using the Ticket objects inside UMRoute.

Subsequent Routes

The UMRouter class supports subsequent route calculations based on an initial set of route results. For example, you can use UMRouter to launch a route calculation, and then use the returned UMCalculateResult to launch a subsequent route calculation for three routes that have the same waypoints, but have an earlier departing time.

You do not need to specify a timestamp for the subsequent calculation. The HERE SDK will automatically return your desired number of results based on whether you specified earlier or later. In other words, you can "slide" the window of interested route results by specifying SubsequentRouteType.EARLIER or (SubsequentRouteType.LATER) and the desired number of results.

The method to perform this calculation is UMRouter.calculateSubsequentRoute(UMCalculateResult, SubsequentRouteType, int, UMRouter.Listener).

Displaying Transit Routes

Before displaying transit routing, you should set the map scheme to include transit so that the MapRoute shows the color of the transit lines.

// sets the map scheme to include transit.
map.setMapScheme(Map.Scheme.NORMAL_DAY_TRANSIT);
Figure 1. Transit Route

The TransitRouteElement Class

Transit route elements, which are route element objects specific to public transit, can be retrieved from the getTransitElement() method in the RouteElement class.

Online Timetables and Fallback Scenarios

Wherever possible, the HERE SDK performs route calculations using the latest online timetable data from municipalities. This is performed automatically when you launch a transit routing request, but the following conditions must be fulfilled:

  • Your application must have an active data connection. If there is no data connection, an estimated routing is performed instead.
  • The route must be between two endpoints—an origin and a destination. Multiple endpoints are not supported.

This type of calculation only returns a maximum of ten route results, even if the limit set in the RouteOptions.setRouteCount(int) exceeds it.

Note: The following route options are ignored in this route calculation mode:
  • setTransitMinimumChangeTime(int)
  • setTransitWalkTimeMultiplier(int)
In addition, the setTransitMaximumChanges(int) option is supported in the primary route result, but the maximum number of changes is capped at ten.
Note: Contractual limitations exist for Online Timetable coverage in Paris, France and Germany. Contact your HERE SDK Sales, Marketing, or Product representative for additional details.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.