Waypoint

public class Waypoint : Codable
extension Waypoint: Equatable
extension Waypoint: CustomStringConvertible

A Waypoint object indicates a location along a route. It may be the route’s origin or destination, or it may be another location that the route visits. A waypoint object indicates the location’s geographic location along with other optional information, such as a name or the user’s direction approaching the waypoint. You create a RouteOptions object using waypoint objects and also receive waypoint objects in the completion handler of the Directions.calculate(_:completionHandler:) method.

  • Declaration

    Swift

    required public init(from decoder: Decoder) throws
  • Declaration

    Swift

    public func encode(to encoder: Encoder) throws
  • Initializes a new waypoint object with the given geographic coordinate and an optional accuracy and name.

    It is recommended that the value of this argument be greater than the horizontalAccuracy property of a CLLocation object obtained from a CLLocationManager object. There is a high likelihood that the user may be located some distance away from a navigable road, for instance if the user is currently on a driveway or inside a building.

    Declaration

    Swift

    public init(coordinate: LocationCoordinate2D, coordinateAccuracy: LocationAccuracy? = nil, name: String? = nil)

    Parameters

    coordinate

    The geographic coordinate of the waypoint.

    coordinateAccuracy

    The maximum distance away from the waypoint that the route may come and still be considered viable. This argument is measured in meters. A negative value means the route may be an indefinite number of meters away from the route and still be considered viable.

    name

    The name of the waypoint. This argument does not affect the route but may help you to distinguish one waypoint from another.

  • Initializes a new waypoint object with the given CLLocation object and an optional heading value and name.

    Note

    This initializer is intended for CLLocation objects created using the CLLocation(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. There is a high likelihood that the user may be located some distance away from a navigable road, for instance if the user is currently on a driveway or inside a building.

  • Initializes a new waypoint object with the given CLLocation object and an optional CLHeading object and name.

    Note

    This initializer is intended for CLLocation objects created using the CLLocation(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. There is a high likelihood that the user may be located some distance away from a navigable road, for instance if the user is currently on a driveway of inside a building.

    Declaration

    Swift

    public init(location: CLLocation, heading: CLHeading? = nil, name: String? = nil)

    Parameters

    location

    A CLLocation object representing the waypoint’s location. This initializer respects the CLLocation class’s coordinate and horizontalAccuracy properties, converting them into the coordinate and coordinateAccuracy properties, respectively.

    heading

    A CLHeading object representing the direction from which the route must approach the waypoint in order to be considered viable. This initializer respects the CLHeading class’s trueHeading property or magneticHeading property, converting it into the headingAccuracy property.

    name

    The name of the waypoint. This argument does not affect the route but may help you to distinguish one waypoint from another.

  • The geographic coordinate of the waypoint.

    Declaration

    Swift

    public let coordinate: LocationCoordinate2D
  • The radius of uncertainty for the waypoint, measured in meters.

    For a route to be considered viable, it must enter this waypoint’s circle of uncertainty. The coordinate property identifies the center of the circle, while this property indicates the circle’s radius. If the value of this property is negative, a route is considered viable regardless of whether it enters this waypoint’s circle of uncertainty, subject to an undefined maximum distance.

    By default, the value of this property is nil.

    Declaration

    Swift

    public var coordinateAccuracy: LocationAccuracy?
  • The geographic coordinate of the waypoint’s target.

    The waypoint’s target affects arrival instructions without affecting the route’s shape. For example, a delivery or ride hailing application may specify a waypoint target that represents a drop-off location. The target determines whether the arrival visual and spoken instructions indicate that the destination is “on the left” or “on the right”.

    By default, this property is set to nil, meaning the waypoint has no target. This property is ignored on the first waypoint of a RouteOptions object, on any waypoint of a MatchOptions object, or on any waypoint of a RouteOptions object if DirectionsOptions.includesSteps is set to false.

    This property corresponds to the waypoint_targets query parameter in the Mapbox Directions and Map Matching APIs.

    Declaration

    Swift

    public var targetCoordinate: LocationCoordinate2D?
  • A Boolean value indicating whether the waypoint may be snapped to a closed road in the resulting RouteResponse.

    If true, the waypoint may be snapped to a road segment that is closed due to a live traffic closure. This property is false by default. This property corresponds to the snapping_include_closures query parameter in the Mapbox Directions API.

    Declaration

    Swift

    public var allowsSnappingToClosedRoad: Bool
  • The straight-line distance from the coordinate specified in the query to the location it was snapped to in the resulting RouteResponse.

    By default, this property is set to nil, meaning the waypoint has no snapped distance.

    Declaration

    Swift

    public var snappedDistance: LocationDistance?
  • The direction from which a route must approach this waypoint in order to be considered viable.

    This property is measured in degrees clockwise from true north. A value of 0 degrees means due north, 90 degrees means due east, 180 degrees means due south, and so on. If the value of this property is negative, a route is considered viable regardless of the direction from which it approaches this waypoint.

    If this waypoint is the first waypoint (the source waypoint), the route must start out by heading in the direction specified by this property. You should always set the headingAccuracy property in conjunction with this property. If the headingAccuracy property is set to nil, this property is ignored.

    For driving directions, this property can be useful for avoiding a route that begins by going in the direction opposite the current direction of travel. For example, if you know the user is moving eastwardly and the first waypoint is the user’s current location, specifying a heading of 90 degrees and a heading accuracy of 90 degrees for the first waypoint avoids a route that begins with a “head west” instruction.

    You should be certain that the user is in motion before specifying a heading and heading accuracy; otherwise, you may be unnecessarily filtering out the best route. For example, suppose the user is sitting in a car parked in a driveway, facing due north, with the garage in front and the street to the rear. In that case, specifying a heading of 0 degrees and a heading accuracy of 90 degrees may result in a route that begins on the back alley or, worse, no route at all. For this reason, it is recommended that you only specify a heading and heading accuracy when automatically recalculating directions due to the user deviating from the route.

    By default, the value of this property is nil, meaning that a route is considered viable regardless of the direction of approach.

    Declaration

    Swift

    public var heading: LocationDirection?
  • The maximum amount, in degrees, by which a route’s approach to a waypoint may differ from heading in either direction in order to be considered viable.

    A value of 0 degrees means that the approach must match the specified heading exactly – an unlikely scenario. A value of 180 degrees or more means that the approach may be as much as 180 degrees in either direction from the specified heading, effectively allowing a candidate route to approach the waypoint from any direction.

    If you set the heading property, you should set this property to a value such as 90 degrees, to avoid filtering out routes whose approaches differ only slightly from the specified heading. Otherwise, if the heading property is set to a negative value, this property is ignored.

    By default, the value of this property is nil, meaning that a route is considered viable regardless of the direction of approach.

    Declaration

    Swift

    public var headingAccuracy: LocationDirection?
  • A Boolean value indicating whether arriving on opposite side is allowed. This property has no effect if DirectionsOptions.includesSteps is set to false. This property corresponds to the approaches query parameter in the Mapbox Directions and Map Matching APIs.

    Declaration

    Swift

    open var allowsArrivingOnOppositeSide: Bool
  • The name of the waypoint.

    This property does not affect the route, but the name is included in the arrival instruction, to help the user distinguish between multiple destinations. The name can also help you distinguish one waypoint from another in the array of waypoints passed into the completion handler of the Directions.calculate(_:completionHandler:) method.

    Declaration

    Swift

    public var name: String?
  • A Boolean value indicating whether the waypoint is significant enough to appear in the resulting routes as a waypoint separating two legs, along with corresponding guidance instructions.

    By default, this property is set to true, which means that each resulting route will include a leg that ends by arriving at the waypoint as RouteLeg.destination and a subsequent leg that begins by departing from the waypoint as RouteLeg.source. Otherwise, if this property is set to false, a single leg passes through the waypoint without specifically mentioning it. Regardless of the value of this property, each resulting route passes through the location specified by the coordinate property, accounting for approach-related properties such as heading.

    With the Mapbox Directions API, set this property to false if you want the waypoint’s location to influence the path that the route follows without attaching any meaning to the waypoint object itself. With the Mapbox Map Matching API, use this property when the DirectionsOptions.includesSteps property is true or when coordinates represents a trace with a high sample rate. This property has no effect if DirectionsOptions.includesSteps is set to false, or if MatchOptions.waypointIndices is non-nil. This property corresponds to the approaches query parameter in the Mapbox Directions and Map Matching APIs.

    Declaration

    Swift

    public var separatesLegs: Bool
  • Declaration

    Swift

    public static func == (lhs: Waypoint, rhs: Waypoint) -> Bool
  • Declaration

    Swift

    public var description: String { get }