Directions

 
open class Directions: NSObject

A Directions object provides you with optimal directions between different locations, or waypoints. The directions object passes your request to the Mapbox Directions API and returns the requested information to a closure (block) that you provide. A directions object can handle multiple simultaneous requests. A RouteOptions object specifies criteria for the results, such as intermediate waypoints, a mode of transportation, or the level of detail to be returned.

Each result produced by the directions object is stored in a Route object. Depending on the RouteOptions object you provide, each route may include detailed information suitable for turn-by-turn directions, or it may include only high-level information such as the distance, estimated travel time, and name of each leg of the trip. The waypoints that form the request may be conflated with nearby locations, as appropriate; the resulting waypoints are provided to the closure.

  • A closure (block) to be called when a directions request is complete.

    If the request was canceled or there was an error obtaining the routes, this parameter may be nil.

    If the request was canceled or there was an error obtaining the routes, this parameter is nil. This is not to be confused with the situation in which no results were found, in which case the array is present but empty.

    Declaration

    Swift

    public typealias CompletionHandler = (_ waypoints: [Waypoint]?, _ routes: [Route]?, _ error: NSError?) -> Void

    Parameters

    waypoints

    An array of Waypoint objects. Each waypoint object corresponds to a Waypoint object in the original RouteOptions object. The locations and names of these waypoints are the result of conflating the original waypoints to known roads. The waypoints may include additional information that was not specified in the original waypoints.
    routes

    An array of Route objects. The preferred route is first; any alternative routes come next if the RouteOptions object’s includesAlternativeRoutes property was set to true. The preferred route depends on the route options object’s profileIdentifier property.
    error

    The error that occurred, or nil if the placemarks were obtained successfully.
    View Source on GitHub

Creating a Directions Object

  • The shared directions object.

    To use this object, a Mapbox access token should be specified in the MGLMapboxAccessToken key in the main application bundle’s Info.plist.

    Declaration

    Swift

    open static let shared = Directions(accessToken: nil)
    View Source on GitHub

  • Initializes a newly created directions object with an optional access token and host.

    Declaration

    Swift

    public init(accessToken: String?, host: String?)

    Parameters

    accessToken

    A Mapbox access token. If an access token is not specified when initializing the directions object, it should be specified in the MGLMapboxAccessToken key in the main application bundle’s Info.plist.
    host

    An optional hostname to the server API. The Mapbox Directions API endpoint is used by default.
    View Source on GitHub

  • Initializes a newly created directions object with an optional access token.

    The directions object sends requests to the Mapbox Directions API endpoint.

    Declaration

    Swift

    public convenience init(accessToken: String?)

    Parameters

    accessToken

    A Mapbox access token. If an access token is not specified when initializing the directions object, it should be specified in the MGLMapboxAccessToken key in the main application bundle’s Info.plist.
    View Source on GitHub

Getting Directions

  • Begins asynchronously calculating the route or routes using the given options and delivers the results to a closure.

    This method retrieves the routes asynchronously over a network connection. If a connection error or server error occurs, details about the error are passed into the given completion handler in lieu of the routes.

    Routes may be displayed atop a Mapbox map. They may be cached but may not be stored permanently. To use the results in other contexts or store them permanently, upgrade to a Mapbox enterprise plan.

    Declaration

    Swift

    open func calculate(_ options: RouteOptions, completionHandler: @escaping CompletionHandler) -> URLSessionDataTask

    Parameters

    options

    A RouteOptions object specifying the requirements for the resulting routes.
    completionHandler

    The closure (block) to call with the resulting routes. This closure is executed on the application’s main thread.

    Return Value

    The data task used to perform the HTTP request. If, while waiting for the completion handler to execute, you no longer want the resulting routes, cancel this task.

    View Source on GitHub

  • The HTTP URL used to fetch the routes from the API.

    After requesting the URL returned by this method, you can parse the JSON data in the response and pass it into the Route.init(json:waypoints:profileIdentifier:) initializer.

    Declaration

    Swift

    open func url(forCalculating options: RouteOptions) -> URL
    View Source on GitHub