SDK for iOS Developer's Guide

Import Route

Import Route is a feature which provides an opportunity to create a custom route object from the route shape, particularly from a list of geo-coordinates (lat, lon).

Your application users will be able to import custom routes from external vendors into the SDK and provide route guidance for these routes. As an example, a route is calculated based on a list of geo-coordinates from GPX file previously saved on the device. In any case, the route will be calculated based on our current map data.

Route calculation is based on the given list of points and navigation mode. The navigation mode is used for route calculation between points and for route recalculation during guidance.

Note:
There is no 100% guarantee that provided route shape can be imported into the route object. In some cases, the resulting route can be different from the original route shape or not be created at all. In order to get a successful route, provided route shape must meet the following criteria:
  • contain no more than 1000 geo coordinates;
  • geo points should be located on the unblocked, navigatable road links;
  • geo points should be matched to the expected road links in the route.
  • avoid using geo points that are located in areas that have complex road networks (complex junctions, overpasses, merging highways, interchanges etc).
  • high density does not mean better route quality. If there are no preferences about roads on some part of the route, corresponding geo points can be removed as they can be approximated automatically by the SDK and as the result, overall performance will be better.

A Route Calculation Example

  1. First create a new array with the desired points.
    // Create an array of points
    NSMutableArray<NMAGeoCoordinates *> *points = [[NSMutableArray alloc] init];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.4992 longitude:13.3956]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.4999 longitude:13.3952]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5007 longitude:13.3948]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5015 longitude:13.3945]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5023 longitude:13.3947]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5031 longitude:13.3953]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5030 longitude:13.3961]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5027 longitude:13.3972]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5025 longitude:13.3980]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5020 longitude:13.3980]];
    [points addObject:[[NMAGeoCoordinates alloc] initWithLatitude:52.5014 longitude:13.3977]];
    
  2. Create a new NMARoutingMode object.
    // Create the NMARoutingMode and set its transport mode & routing type
    NMARoutingMode* routingMode = [[NMARoutingMode alloc] initWithRoutingType:NMARoutingTypeFastest transportMode:NMATransportModeCar routingOptions:0];
    
  3. Calculate the route by calling calculateRouteWithPoints:routingMode:completionBlock:.
    // Calculate route
    [coreRouter calculateRouteWithPoints:points routingMode:routingMode
        completionBlock:^(NMARouteResult *routeResult, NMARoutingError error) {
          // If the route was calculated successfully
          if (!error && routeResult && routeResult.routes.count > 0)
          {
            NMARoute* route = [routes objectAtIndex:0];
            // Render the route on the map
            mapRoute = [NMAMapRoute mapRouteWithRoute:route];
            [mapView addMapObject:mapRoute];
          }
          else if(error)
          {
            // Display a message indicating route calculation failure
          }
        }];
    
Figure 1. Imported route