Route

open class Route: NSObject, NSSecureCoding

A Route object defines a single route that the user can follow to visit a series of waypoints in order. The route object includes information about the route, such as its distance and expected travel time. Depending on the criteria used to calculate the route, the route object may also include detailed turn-by-turn instructions.

Typically, you do not create instances of this class directly. Instead, you receive route objects when you request directions using the Directions.calculate(_:completionHandler:) method. However, if you use the Directions.url(forCalculating:) method instead, you can pass the results of the HTTP request into this class’s initializer.

  • Initializes a new route object with the given JSON dictionary representation and waypoints.

    This initializer is intended for use in conjunction with the Directions.url(forCalculating:) method.

    Declaration

    Swift

    @objc public convenience init(json: [String: Any], waypoints: [Waypoint], routeOptions: RouteOptions)

    Parameters

    json

    A JSON dictionary representation of the route as returned by the Mapbox Directions API.

    waypoints

    An array of waypoints that the route visits in chronological order.

    routeOptions

    The RouteOptions used to create the request.

  • An array of geographic coordinates defining the path of the route from start to finish.

    This array may be nil or simplified depending on the routeShapeResolution property of the original RouteOptions object.

    Using the Mapbox Maps SDK for iOS or Mapbox Maps SDK for macOS, you can create an MGLPolyline object using these coordinates to display an overview of the route on an MGLMapView.

    Declaration

    Swift

    @objc open let coordinates: [CLLocationCoordinate2D]?
  • The number of coordinates.

    The value of this property may be zero or reduced depending on the routeShapeResolution property of the original RouteOptions object.

    Note

    This initializer is intended for Objective-C usage. In Swift code, use the coordinates.count property.

    Declaration

    Swift

    @objc open var coordinateCount: UInt
  • Retrieves the coordinates.

    The array may be empty or simplified depending on the routeShapeResolution property of the original RouteOptions object.

    Using the Mapbox Maps SDK for iOS or Mapbox Maps SDK for macOS, you can create an MGLPolyline object using these coordinates to display an overview of the route on an MGLMapView.

    Precondition

    coordinates must be large enough to hold coordinateCount instances of CLLocationCoordinate2D.

    Note

    This initializer is intended for Objective-C usage. In Swift code, use the coordinates property.

    Declaration

    Swift

    @objc open func getCoordinates(_ coordinates: UnsafeMutablePointer<CLLocationCoordinate2D>)

    Parameters

    coordinates

    A pointer to a C array of CLLocationCoordinate2D instances. On output, this array contains all the vertices of the overlay.

  • An array of RouteLeg objects representing the legs of the route.

    The number of legs in this array depends on the number of waypoints. A route with two waypoints (the source and destination) has one leg, a route with three waypoints (the source, an intermediate waypoint, and the destination) has two legs, and so on.

    To determine the name of the route, concatenate the names of the route’s legs.

    Declaration

    Swift

    @objc open let legs: [RouteLeg]
  • The route’s distance, measured in meters.

    The value of this property accounts for the distance that the user must travel to traverse the path of the route. It is the sum of the distance properties of the route’s legs, not the sum of the direct distances between the route’s waypoints. You should not assume that the user would travel along this distance at a fixed speed.

    Declaration

    Swift

    @objc open let distance: CLLocationDistance
  • The route’s expected travel time, measured in seconds.

    The value of this property reflects the time it takes to traverse the entire route. It is the sum of the expectedTravelTime properties of the route’s legs. If the route was calculated using the MBDirectionsProfileIdentifierAutomobileAvoidingTraffic profile, this property reflects current traffic conditions at the time of the request, not necessarily the traffic conditions at the time the user would begin the route. For other profiles, this property reflects travel time under ideal conditions and does not account for traffic congestion. If the route makes use of a ferry or train, the actual travel time may additionally be subject to the schedules of those services.

    Do not assume that the user would travel along the route at a fixed speed. For more granular travel times, use the RouteLeg.expectedTravelTime or RouteStep.expectedTravelTime. For even more granularity, specify the AttributeOptions.expectedTravelTime option and use the RouteLeg.expectedSegmentTravelTimes property.

    Declaration

    Swift

    @objc open let expectedTravelTime: TimeInterval
  • RouteOptions used to create the directions request.

    The route options object’s profileIdentifier property reflects the primary mode of transportation used for the route. Individual steps along the route might use different modes of transportation as necessary.

    Declaration

    Swift

    @objc open let routeOptions: RouteOptions
  • The access token used to make the directions request.

    This property is set automatically if a request is made via Directions.calculate(_:completionHandler:).

    Declaration

    Swift

    @objc open var accessToken: String?
  • The endpoint used to make the directions request.

    This property is set automatically if a request is made via Directions.calculate(_:completionHandler:).

    Declaration

    Swift

    @objc open var apiEndpoint: URL?
  • A unique identifier for a directions request.

    Each route produced by a single call to Directions.calculate(_:completionHandler:) has the same route identifier.

    Declaration

    Swift

    @objc open var routeIdentifier: String?