RouteOptions

open class RouteOptions : DirectionsOptions

A RouteOptions object is a structure that specifies the criteria for results returned by the Mapbox Directions API.

Pass an instance of this class into the Directions.calculate(_:completionHandler:) method.

  • Initializes a route options object for routes between the given waypoints and an optional profile identifier.

    Declaration

    Swift

    public required init(waypoints: [Waypoint], profileIdentifier: ProfileIdentifier? = nil, queryItems: [URLQueryItem]? = nil)

    Parameters

    waypoints

    An array of Waypoint objects representing locations that the route should visit in chronological order. The array should contain at least two waypoints (the source and destination) and at most 25 waypoints. (Some profiles, such as ProfileIdentifier.automobileAvoidingTraffic, may have lower limits.)

    profileIdentifier

    A string specifying the primary mode of transportation for the routes. ProfileIdentifier.automobile is used by default.

    queryItems

    URL query items to be parsed and applied as configuration to the resulting options.

  • Initializes a route options object for routes between the given locations and an optional profile identifier.

    Note

    This initializer is intended for CLLocation objects created using the CLLocation.init(latitude:longitude:) initializer. If you intend to use a CLLocation object obtained from a CLLocationManager object, consider increasing the horizontalAccuracy or set it to a negative value to avoid overfitting, since the Waypoint class’s coordinateAccuracy property represents the maximum allowed deviation from the waypoint.

    Declaration

    Swift

    public convenience init(locations: [CLLocation], profileIdentifier: ProfileIdentifier? = nil, queryItems: [URLQueryItem]? = nil)

    Parameters

    locations

    An array of CLLocation objects representing locations that the route should visit in chronological order. The array should contain at least two locations (the source and destination) and at most 25 locations. Each location object is converted into a Waypoint object. This class respects the CLLocation class’s coordinate and horizontalAccuracy properties, converting them into the Waypoint class’s coordinate and coordinateAccuracy properties, respectively.

    profileIdentifier

    A string specifying the primary mode of transportation for the routes. ProfileIdentifier.automobile is used by default.

    queryItems

    URL query items to be parsed and applied as configuration to the resulting options.

  • Initializes a route options object for routes between the given geographic coordinates and an optional profile identifier.

    Declaration

    Swift

    public convenience init(coordinates: [LocationCoordinate2D], profileIdentifier: ProfileIdentifier? = nil, queryItems: [URLQueryItem]? = nil)

    Parameters

    coordinates

    An array of geographic coordinates representing locations that the route should visit in chronological order. The array should contain at least two locations (the source and destination) and at most 25 locations. Each coordinate is converted into a Waypoint object.

    profileIdentifier

    A string specifying the primary mode of transportation for the routes. ProfileIdentifier.automobile is used by default.

    queryItems

    URL query items to be parsed and applied as configuration to the resulting options.

  • Initializes an equivalent route options object from a match options object. Desirable for building a navigation experience from map matching.

    Declaration

    Swift

    public convenience init(matchOptions: MatchOptions)

    Parameters

    matchOptions

    The MatchOptions that is being used to convert to a RouteOptions object.

  • A Boolean value that indicates whether a returned route may require a point U-turn at an intermediate waypoint.

    If the value of this property is true, a returned route may require an immediate U-turn at an intermediate waypoint. At an intermediate waypoint, if the value of this property is false, each returned route may continue straight ahead or turn to either side but may not U-turn. This property has no effect if only two waypoints are specified.

    Set this property to true if you expect the user to traverse each leg of the trip separately. For example, it would be quite easy for the user to effectively “U-turn” at a waypoint if the user first parks the car and patronizes a restaurant there before embarking on the next leg of the trip. Set this property to false if you expect the user to proceed to the next waypoint immediately upon arrival. For example, if the user only needs to drop off a passenger or package at the waypoint before continuing, it would be inconvenient to perform a U-turn at that location.

    The default value of this property is false when the profile identifier is ProfileIdentifier.automobile or ProfileIdentifier.automobileAvoidingTraffic and true otherwise.

    Declaration

    Swift

    open var allowsUTurnAtWaypoint: Bool
  • The route classes that the calculated routes will avoid.

    Currently, you can only specify a single road class to avoid.

    Declaration

    Swift

    open var roadClassesToAvoid: RoadClasses
  • The route classes that the calculated routes will allow.

    This property has no effect unless the profile identifier is set to ProfileIdentifier.automobile or ProfileIdentifier.automobileAvoidingTraffic.

    Declaration

    Swift

    open var roadClassesToAllow: RoadClasses
  • The number that influences whether the route should prefer or avoid alleys or narrow service roads between buildings. If this property isn’t explicitly set, the Directions API will choose the most reasonable value.

    This property has no effect unless the profile identifier is set to ProfileIdentifier.automobile or ProfileIdentifier.walking.

    The value of this property must be at least DirectionsPriority.low and at most DirectionsPriority.high. DirectionsPriority.medium neither prefers nor avoids alleys, while a negative value between DirectionsPriority.low and DirectionsPriority.medium avoids alleys, and a positive value between DirectionsPriority.medium and DirectionsPriority.high prefers alleys. A value of 0.9 is suitable for pedestrians who are comfortable with walking down alleys.

    Declaration

    Swift

    open var alleyPriority: DirectionsPriority?
  • The number that influences whether the route should prefer or avoid roads or paths that are set aside for pedestrian-only use (walkways or footpaths). If this property isn’t explicitly set, the Directions API will choose the most reasonable value.

    This property has no effect unless the profile identifier is set to ProfileIdentifier.walking. You can adjust this property to avoid sidewalks and crosswalks that are mapped as separate footpaths, which may be more granular than needed for some forms of pedestrian navigation.

    The value of this property must be at least DirectionsPriority.low and at most DirectionsPriority.high. DirectionsPriority.medium neither prefers nor avoids walkways, while a negative value between DirectionsPriority.low and DirectionsPriority.medium avoids walkways, and a positive value between DirectionsPriority.medium and DirectionsPriority.high prefers walkways. A value of −0.1 results in less verbose routes in cities where sidewalks and crosswalks are generally mapped as separate footpaths.

    Declaration

    Swift

    open var walkwayPriority: DirectionsPriority?
  • The expected uniform travel speed measured in meters per second. If this property isn’t explicitly set, the Directions API will choose the most reasonable value.

    This property has no effect unless the profile identifier is set to ProfileIdentifier.walking. You can adjust this property to account for running or for faster or slower gaits. When the profile identifier is set to another profile identifier, such as ProfileIdentifier.driving, this property is ignored in favor of the expected travel speed on each road along the route. This property may be supported by other routing profiles in the future.

    The value of this property must be at least CLLocationSpeed.minimumWalking and at most CLLocationSpeed.maximumWalking. CLLocationSpeed.normalWalking corresponds to a typical preferred walking speed.

    Declaration

    Swift

    open var speed: LocationSpeed?
  • The desired arrival time, ignoring seconds precision, in the local time at the route destination.

    This property has no effect unless the profile identifier is set to ProfileIdentifier.automobile.

    Declaration

    Swift

    open var arriveBy: Date?
  • The desired departure time, ignoring seconds precision, in the local time at the route origin

    This property has no effect unless the profile identifier is set to ProfileIdentifier.automobile or ProfileIdentifier.automobileAvoidingTraffic.

    Declaration

    Swift

    open var departAt: Date?
  • A Boolean value indicating whether alternative routes should be included in the response.

    If the value of this property is false, the server only calculates a single route that visits each of the waypoints. If the value of this property is true, the server attempts to find additional reasonable routes that visit the waypoints. Regardless, multiple routes are only returned if it is possible to visit the waypoints by a different route without significantly increasing the distance or travel time. The alternative routes may partially overlap with the preferred route, especially if intermediate waypoints are specified.

    Alternative routes may take longer to calculate and make the response significantly larger, so only request alternative routes if you intend to display them to the user or let the user choose them over the preferred route. For example, do not request alternative routes if you only want to know the distance or estimated travel time to a destination.

    The default value of this property is false.

    Declaration

    Swift

    open var includesAlternativeRoutes: Bool
  • A Boolean value indicating whether the route includes a ManeuverType.exitRoundabout or ManeuverType.exitRotary step when traversing a roundabout or rotary, respectively.

    If this option is set to true, a route that traverses a roundabout includes both a ManeuverType.takeRoundabout step and a ManeuverType.exitRoundabout step; likewise, a route that traverses a large, named roundabout includes both a ManeuverType.takeRotary step and a ManeuverType.exitRotary step. Otherwise, it only includes a ManeuverType.takeRoundabout or ManeuverType.takeRotary step. This option is set to false by default.

    Declaration

    Swift

    open var includesExitRoundaboutManeuver: Bool
  • A Boolean value indicating whether Directions can refresh time-dependent properties of the RouteLegs of the resulting Routes.

    To refresh the RouteLeg.expectedSegmentTravelTimes, RouteLeg.segmentSpeeds, and RouteLeg.segmentCongestionLevels properties, use the Directions.refreshRoute(responseIdentifier:routeIndex:fromLegAtIndex:completionHandler:) method. This property is ignored unless profileIdentifier is ProfileIdentifier.automobileAvoidingTraffic. This option is set to false by default.

    Declaration

    Swift

    open var refreshingEnabled: Bool
  • The maximum vehicle height.

    If this parameter is provided, Directions will compute a route that includes only roads with a height limit greater than or equal to the max vehicle height or no height limit. This property is supported by DirectionsProfileIdentifier.automobile and DirectionsProfileIdentifier.automobileAvoidingTraffic profiles. The value must be between 0 and 10 when converted to meters.

    Declaration

    Swift

    open var maximumHeight: Measurement<UnitLength>?
  • The maximum vehicle width.

    If this parameter is provided, Directions will compute a route that includes only roads with a width limit greater than or equal to the max vehicle width or no width limit. This property is supported by DirectionsProfileIdentifier.automobile and DirectionsProfileIdentifier.automobileAvoidingTraffic profiles. The value must be between 0 and 10 when converted to meters.

    Declaration

    Swift

    open var maximumWidth: Measurement<UnitLength>?
  • A radius around the starting point in which the API will avoid returning any significant maneuvers.

    Use this option when the vehicle is traveling at a significant speed to avoid dangerous maneuvers when re-routing. If a route is not found using the specified value, it will be ignored. Note that if a large radius is used, the API may ignore an important turn and return a long straight path before the first maneuver.

    This value is clamped to LocationDistance.minimumManeuverIgnoringRadius and LocationDistance.maximumManeuverIgnoringRadius.

    Declaration

    Swift

    open var initialManeuverAvoidanceRadius: LocationDistance? { get set }