> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/ja/navigation/llms.txt)

# Route generation

The routes used in the Navigation SDK are generated by the [Mapbox Directions API](https://docs.mapbox.com/api/navigation/#directions). When you install the Navigation SDK, it provides a convenient way to access the Mapbox Directions API in iOS applications.

To generate a route, you'll create a new [`NavigationRoutes`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationroutes/) struct. In most cases, you'll also use the [`NavigationRouteOptions`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationrouteoptions/) class to set a few options.

[`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/routingprovider/) is the main protocol responsible for generating routes. It's implemented by the [`MapboxRoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxroutingprovider/) class, which is part of the Mapbox Navigation SDK. It has two main methods:

1.  Calculate routes using Mapbox Directions API: [`calculateRoutes(options:)`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxroutingprovider/calculateroutes(options:)-1dppy/)
2.  Calculate routes using Mapbox Map Matching API [`calculateRoutes(options:)`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxroutingprovider/calculateroutes(options:)-2y7hw/) method.

An instance of [`MapboxRoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxroutingprovider/) can be obtained from [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) which is itself obtained from [`MapboxNavigationProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigationprovider/). `MapboxNavigationProvider` is the main entrypoint of the Mapbox Navigation SDK and you have to create it yourself. Usually the route generation process looks like this:

```swift
let mapboxNavigationProvider = MapboxNavigationProvider(coreConfig: .init())
let mapboxNavigation = navigationProvider.mapboxNavigation
let routingProvider = mapboxNavigation.routingProvider()
let routes = try await routingProvider.calculateRoutes(options: routeOptions).value
```

Below are examples of how you can use specific options to generate routes for a few scenarios.

## Request a route in a specific direction

With the Navigation SDK, you can consider the direction a user's device is facing and request a route starting in a specific direction. To receive a route in a specific direction (for example, the direction a user is traveling or the direction a device is facing), pass in the user's location `heading` value. This property corresponds to the angles in the [bearings](https://docs.mapbox.com/api/navigation/#retrieve-directions) query parameter in the Mapbox Directions and Map Matching APIs.

**Waypoint**: In the adjacent diagram, the blue dot with white stroke is the device location. Imagine this is the first (origin) `Waypoint` in a Directions API request.

**Heading**: The [`Waypoint.heading`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxdirections/waypoint/heading/) can be used to influence the direction in which a route leg should begin. The `heading` value is the angle clockwise from true north between 0 and 359. For example, when the `heading` value is 0, the heading direction is due north. In the adjacent diagram, the pink arrow is the direction that the device is the `heading` (which is due west or 270°).

**Heading accuracy**: The [`Waypoint.headingAccuracy`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxdirections/waypoint/headingaccuracy/) is the range of degrees by which a route can deviate from the `Waypoint.heading` angle and still be recommended. The semi-transparent blue area illustrates `headingAccuracy`. In this example `headingAccuracy` is 90° (45° in either direction from the heading angle).

> **Note: Default heading**
> 
> The system sets the default value for `heading` to −1°, meaning it will not take the heading into account when calculating a route.

### Consider the direction a user is already traveling

If you need to request a route that's continuing along the path that the user is traveling, set the [`Waypoint.heading`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxdirections/waypoint/heading/) to use [`CLLocation.course`](https://developer.apple.com/documentation/corelocation/cllocation/1423832-course). This may be appropriate for driving directions. Consider that the phone may be in a center cup holder, facing the driver rather than the rear-view mirror, as the car moves in a forward direction. You can also set a custom [`Waypoint.headingAccuracy`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxdirections/waypoint/headingaccuracy/).

This can be applied to any waypoint including the origin, stops along the route, and the destination.

```swift
let mapboxNavigation = navigationProvider.mapboxNavigation
guard let location = mapboxNavigation.navigation().currentLocationMatching?.location else { return }
var userWaypoint = Waypoint(location: location)
userWaypoint.heading = location.course
userWaypoint.headingAccuracy = 90.0
```

## Specify a side of the road to approach

By default, routes generated will approach waypoints on either side of road. You can override the default by setting [`Waypoint.allowsArrivingOnOppositeSide`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxdirections/waypoint/allowsarrivingonoppositeside/) to `false`. This will require that the route has the driver approach the waypoint on the same side of the road the waypoint is on. `allowsArrivingOnOppositeSide` corresponds to the [approaches](https://docs.mapbox.com/api/navigation/#retrieve-directions) query parameter in the Mapbox Directions and Map Matching APIs.

```swift
let location: CLLocation = ...
var userWaypoint = Waypoint(location: location)
userWaypoint.allowsArrivingOnOppositeSide = false
```

## Include multiple stops

The Mapbox Directions API requires at least two waypoints to generate a route. If your route involves several pick-up and drop-off points, you can add up to 25 coordinates (including the origin and destination) using the [`automobile`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxdirections/profileidentifier/automobile/) profile or three coordinates using the [`automobileAvoidingTraffic`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxdirections/profileidentifier/automobileavoidingtraffic/) profile. These coordinates are treated as stops between the origin and destination in the order that you add them — the first waypoint is the origin and the second waypoint is the first stop:

```swift
let routeOptions = NavigationRouteOptions(waypoints: [
    Waypoint(coordinate: CLLocationCoordinate2D(latitude: 37.77766, longitude: -122.43199)),
    Waypoint(coordinate: CLLocationCoordinate2D(latitude: 37.77609, longitude: -122.43292)),
    Waypoint(coordinate: CLLocationCoordinate2D(latitude: 37.77536, longitude: -122.43494)),
])

let core = navigationProvider.mapboxNavigation
let routingProvider = core.routingProvider()
let routes = try await routingProvider.calculateRoutes(options: routeOptions).value
```

### Silent waypoints

The [`Waypoint.separatesLegs`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxdirections/waypoint/separateslegs/) property determines if a waypoint will be treated as a stop between legs or only influence the route without mentioning it in maneuver instructions.

By default `Waypoint.separatesLegs` is equal to `true` meaning the waypoint will appear in the resulting routes as a waypoint separating two legs, along with corresponding guidance instructions.

If you want to make sure that the route you request passes through the waypoint without specifically mentioning it, set `Waypoint.separatesLegs` equal to `false`.

### Optimized routes

If you want to generate a route that will arrive at the waypoints in the fastest order (not necessarily in a specific order), see the [Optimization API documentation](https://docs.mapbox.com/api/navigation/#optimization).

### Route generation in offline mode

Default implementation of protocol [`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/routingprovider/) named [`MapboxRoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxroutingprovider/) automatically generates routes using the onboard routing engine when the device is offline, providing enough cached tiles are available.