Planning a route

VERSION 0.2.1455

Requesting routes

To calculate a route from A to B, you need to provide route planning criteria. They are built using the RoutingOptions class. You can use RoutingOptionsBuilder to choose the properties that you need and create RoutingOptions. The only required parameters are origin and destination. There are multiple optional parameters that you can use to shape the route planning criteria to fit your use cases. For a detailed description of available parameters, see the Routing API, Calculate Route documentation.

1let amsterdamCoordinate = CLLocationCoordinate2DMake(52.3764527, 4.9062047)
2let amsterdamAddress = Address(
3 streetNumber: "30",
4 streetName: "Basisweg",
5 municipality: "Amsterdam",
6 postalCode: "1043 AP",
7 country: "The Netherlands"
9let amsterdamPlace = Place(coordinate: amsterdamCoordinate, name: "Amsterdam", address: amsterdamAddress)
10let berlinCoordinate = CLLocationCoordinate2DMake(52.5069751, 13.3631919)
11let berlinPlace = Place(coordinate: berlinCoordinate, name: "Berlin")
12let hagueCoordinate = CLLocationCoordinate2DMake(52.078663, 4.288788)
13let hagueAddress = Address(
14 streetNumber: "70",
15 streetName: "De Perponcherstraat",
16 municipality: "Den Haag",
17 postalCode: "2518 SW",
18 country: "The Netherlands"
20let haguePlace = Place(coordinate: hagueCoordinate, name: "Den Haag", address: hagueAddress)
22let itinerary = Itinerary(
23 origin: ItineraryPoint(place: amsterdamPlace),
24 destination: ItineraryPoint(place: berlinPlace),
25 waypoints: [ItineraryPoint(place: haguePlace)]
28let options = RoutingOptionsBuilder(itinerary: itinerary)
29 .with(routeType: .efficient)
30 .with(travelMode: .car)
31 .build()

Once you have a RoutingOptions object, pass it to the planRoute method. The result of the planning is passed into the completion block passed to the 'planRoute' method. The result can be either .success(response) if planning succeeded, or .failure(error) if planning failed.

1routingService.planRoute(options: options) { result in
2 switch result {
3 case let .success(response):
4 if (response.routes?.first) != nil {
5 // success case
6 }
7 case .failure:
8 // failure case
9 break
10 }

Adjusting route planning criteria

Route types

The routeType parameter specifies the type of optimization used when calculating routes:

  • fast - Route calculation is optimized by travel time, while keeping the routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that only save very little time.
  • short - Route calculation is optimized so that a good compromise between small travel time and short travel distance is achieved.
  • efficient - Route calculation is optimized by fuel/energy consumption.
  • thrilling - Route calculation is optimized so that routes include interesting or challenging roads and use as few motorways as possible.
    • You can choose the level of turns included and also the degree of hilliness. See the hilliness and windingness parameters to set this.
    • There is a limit of 900km on routes planned with routeType=thrilling.

The default value is fast.


The RoutingOptions.avoidTypes parameter specifies something that the route calculation should try to avoid when determining the route. The avoid can be specified multiple times. Possible values are:

Vehicle profile

Vehicle profile relates to a set of parameters that are used to provide extra information about the vehicle specification. It also provides information about the current state, e.g., the level of fuel.

Some roads in the map have vehicle and time dependent restrictions. For example, roads may restrict traffic to pedestrians, or can only be used by electric vehicles. Various road types may prohibit vehicles carrying hazardous materials. Tunnels may only be passable by vehicles up to a maximum height, and for trucks, with the proper tunnel code. These restrictions may affect the routes that can be planned for the user’s vehicle.

Key parameters defining vehicle profiles:

  • Vehicle type, e.g., car or motorcycle.
  • Engine type, e.g., combustion or electric. For pedestrians and bicycles, no engine is allowed.
  • Consumption parameters used to adjust the overall range prediction of the vehicle.
  • Vehicle dimensions.
  • Hazardous payload describing the classification of carrying hazardous materials carried by the vehicle.
  • Tunnel codes describing which tunnels can be used.

Vehicle profile properties are valid only at the current point in time and they get updated over time, e.g., the consumption curve. Vehicle profile is also useful during free driving mode without a route, e.g., to steer range features like a 360 range around the current position.

Planning errors

If any errors occurred during the planning, the result returned by the completion block will be .failure(error). The error type is NSError for common errors (e.g., Networking) and RoutingError for routing-specific errors. There are a few RoutingError codes that are returned in different situations.

  • unknown - Routing call ended with an unknown error.
  • badInput - The combination of input parameters was not valid.
  • noRouteFound - No valid route could be found.
  • internalError - The service encountered an unexpected error while fulfilling the request.
  • cannotRestoreBaseroute - The route could not be reconstructed using supportingPoints.
  • serviceUnavailable - The service is not ready to handle the request.
  • deserialization - Deserialization of the routing response failed.
  • network - Routing network call failed.
  • computationTimeout -The request reached an internal computation time threshold and timed out.
  • apiKeyError - Indicates that the API key has no permission to access this resource.
  • mapMatchingFailure - One of the input points (Origin, Destination, Waypoints) could not be matched to the map because no drivable section near this point could be found.
  • cancelled - The request has been cancelled.