RouteStep

open class RouteStep: NSObject, NSSecureCoding

A RouteStep object represents a single distinct maneuver along a route and the approach to the next maneuver. The route step object corresponds to a single instruction the user must follow to complete a portion of the route. For example, a step might require the user to turn then follow a road.

You do not create instances of this class directly. Instead, you receive route step objects as part of route objects when you request directions using the Directions.calculate(_:completionHandler:) method, setting the includesSteps option to true in the RouteOptions object that you pass into that method.

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

    Normally, you do not create instances of this class directly. Instead, you receive route step objects as part of route objects when you request directions using the Directions.calculateDirections(options:completionHandler:) method, setting the includesSteps option to true in the RouteOptions object that you pass into that method.

    Declaration

    Swift

    public convenience init(json: [String: Any])

    Parameters

    json

    A JSON dictionary representation of a route step object as returnd by the Mapbox Directions API.

  • An array of geographic coordinates defining the path of the route step from the location of the maneuver to the location of the next step’s maneuver.

    The value of this property may be nil, for example when the maneuver type is arrive.

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

    Declaration

    Swift

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

    The value of this property may be zero, for example when the maneuver type is arrive.

    Note

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

    Declaration

    Swift

    open var coordinateCount: UInt
  • Retrieves the coordinates.

    The array may be empty, for example when the maneuver type is arrive.

    Using the Mapbox iOS SDK or Mapbox macOS SDK, you can create an MGLPolyline object using these coordinates to display a portion of a 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

    open func getCoordinates(_ coordinates: UnsafeMutablePointer<CLLocationCoordinate2D>) -> Bool

    Parameters

    coordinates

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

    Return Value

    True if the step has coordinates and coordinates has been populated, or false if the step has no coordinates and coordinates has not been modified.

  • A string with instructions explaining how to perform the step’s maneuver.

    You can display this string or read it aloud to the user. The string does not include the distance to or from the maneuver. If you need localized or customized instructions, you can construct them yourself from the step’s other properties or use osrm-text-instructions.

    Note

    If you use MapboxDirections.swift with the Mapbox Directions API, this property is formatted for display to the user. If you use OSRM directly, this property contains a basic string that only includes the maneuver type and direction. Use osrm-text-instructions to construct a complete instruction string for display.

    Declaration

    Swift

    open let instructions: String
  • The user’s heading immediately before performing the maneuver.

    Declaration

    Swift

    open let initialHeading: CLLocationDirection?
  • The user’s heading immediately after performing the maneuver.

    The value of this property may differ from the user’s heading after traveling along the road past the maneuver.

    Declaration

    Swift

    open let finalHeading: CLLocationDirection?
  • The type of maneuver required for beginning this step.

    Declaration

    Swift

    open let maneuverType: ManeuverType?
  • Additional directional information to clarify the maneuver type.

    Declaration

    Swift

    open let maneuverDirection: ManeuverDirection?
  • The location of the maneuver at the beginning of this step.

    Declaration

    Swift

    open let maneuverLocation: CLLocationCoordinate2D
  • The number of exits from the previous maneuver up to and including this step’s maneuver.

    If the maneuver takes place on a surface street, this property counts intersections. The number of intersections does not necessarily correspond to the number of blocks. If the maneuver takes place on a grade-separated highway (freeway or motorway), this property counts highway exits but not highway entrances. If the maneuver is a roundabout maneuver, the exit index is the number of exits from the approach to the recommended outlet. For the signposted exit numbers associated with a highway exit, use the exitCodes property.

    In some cases, the number of exits leading to a maneuver may be more useful to the user than the distance to the maneuver.

    Declaration

    Swift

    open let exitIndex: Int?
  • Any exit numbers assigned to the highway exit at the maneuver.

    This property is only set when the maneuverType is ManeuverType.takeOffRamp. For the number of exits from the previous maneuver, regardless of the highway’s exit numbering scheme, use the exitIndex property. For the route reference codes associated with the connecting road, use the destinationCodes property. For the names associated with a roundabout exit, use the exitNames property.

    An exit number is an alphanumeric identifier posted at or ahead of a highway off-ramp. Exit numbers may increase or decrease sequentially along a road, or they may correspond to distances from either end of the road. An alphabetic suffix may appear when multiple exits are located in the same interchange. If multiple exits are combined into a single exit, the step may have multiple exit codes.

    Declaration

    Swift

    open let exitCodes: [String]?
  • The names of the roundabout exit.

    This property is only set for roundabout (traffic circle or rotary) maneuvers. For the signposted names associated with a highway exit, use the destinations property. For the signposted exit numbers, use the exitCodes property.

    If you display a name to the user, you may need to abbreviate common words like “East” or “Boulevard” to ensure that it fits in the allotted space.

    Declaration

    Swift

    public let exitNames: [String]?
  • The step’s distance, measured in meters.

    The value of this property accounts for the distance that the user must travel to go from this step’s maneuver location to the next step’s maneuver location. It is not the sum of the direct distances between the route’s waypoints, nor should you assume that the user would travel along this distance at a fixed speed.

    Declaration

    Swift

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

    The value of this property reflects the time it takes to go from this step’s maneuver location to the next step’s maneuver location under ideal conditions. You should not assume that the user would travel along the step at a fixed speed. The actual travel time may vary based on the weather, traffic conditions, road construction, and other variables. If the step makes use of a ferry or train, the actual travel time may additionally be subject to the schedules of those services.

    Declaration

    Swift

    open let expectedTravelTime: TimeInterval
  • The names of the road or path leading from this step’s maneuver to the next step’s maneuver.

    If the maneuver is a turning maneuver, the step’s names are the name of the road or path onto which the user turns. If you display a name to the user, you may need to abbreviate common words like “East” or “Boulevard” to ensure that it fits in the allotted space.

    If the maneuver is a roundabout maneuver, the outlet to take is named in the exitNames property; the names property is only set for large roundabouts that have their own names.

    Declaration

    Swift

    open let names: [String]?
  • Any route reference codes assigned to the road or path leading from this step’s maneuver to the next step’s maneuver.

    A route reference code commonly consists of an alphabetic network code, a space or hyphen, and a route number. You should not assume that the network code is globally unique: for example, a network code of “NH” may indicate a “National Highway” or “New Hampshire”. Moreover, a route number may not even uniquely identify a route within a given network.

    If a highway ramp is part of a numbered route, its reference code is contained in this property. On the other hand, guide signage for a highway ramp usually indicates route reference codes of the adjoining road; use the destinationCodes property for those route reference codes.

    Declaration

    Swift

    open let codes: [String]?
  • The mode of transportation used for the step.

    This step may use a different mode of transportation than the overall route.

    Declaration

    Swift

    open let transportType: TransportType?
  • Any route reference codes that appear on guide signage for the road leading from this step’s maneuver to the next step’s maneuver.

    This property is typically available in steps leading to or from a freeway or expressway. This property contains route reference codes associated with a road later in the route. If a highway ramp is itself part of a numbered route, its reference code is contained in the codes property. For the signposted exit numbers associated with a highway exit, use the exitCodes property.

    A route reference code commonly consists of an alphabetic network code, a space or hyphen, and a route number. You should not assume that the network code is globally unique: for example, a network code of “NH” may indicate a “National Highway” or “New Hampshire”. Moreover, a route number may not even uniquely identify a route within a given network. A destination code for a divided road is often suffixed with the cardinal direction of travel, for example “I 80 East”.

    Declaration

    Swift

    public let destinationCodes: [String]?
  • Destinations, such as control cities, that appear on guide signage for the road leading from this step’s maneuver to the next step’s maneuver.

    This property is typically available in steps leading to or from a freeway or expressway.

    Declaration

    Swift

    open let destinations: [String]?
  • An array of intersections along the step.

    Each item in the array corresponds to a cross street, starting with the intersection at the maneuver location indicated by the coordinates property and continuing with each cross street along the step.

    Declaration

    Swift

    public let intersections: [Intersection]?