Directions

 
@objc(MBDirections)
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 RouteCompletionHandler = (_ 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

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

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

    Declaration

    Swift

    public typealias MatchCompletionHandler = (_ matches: [Match]?, _ error: NSError?) -> Void

    Parameters

    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

    @objc(sharedDirections)
public static let shared: Directions
    View Source on GitHub

  • The API endpoint to use when requesting directions.

    Declaration

    Swift

    @objc
public private(set) var apiEndpoint: URL
    View Source on GitHub

  • The Mapbox access token to associate with the request.

    Declaration

    Swift

    @objc
public let accessToken: String
    View Source on GitHub

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

    Declaration

    Swift

    @objc
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

    @objc
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 routes using the given options and delivers the results to a closure.

    This method retrieves the routes asynchronously from the Mapbox Directions API 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

    @discardableResult
@objc(calculateDirectionsWithOptions:completionHandler:)
open func calculate(_ options: RouteOptions, completionHandler: @escaping RouteCompletionHandler) -> 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

  • Begins asynchronously calculating matches using the given options and delivers the results to a closure.

    This method retrieves the matches asynchronously from the Mapbox Map Matching API 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.

    To get Routes based on these matches, use the calculateRoutes(matching:completionHandler:) method instead.

    Declaration

    Swift

    @discardableResult
@objc(calculateMatchesWithOptions:completionHandler:)
open func calculate(_ options: MatchOptions, completionHandler: @escaping MatchCompletionHandler) -> URLSessionDataTask

    Parameters

    options

    A MatchOptions object specifying the requirements for the resulting matches.
    completionHandler

    The closure (block) to call with the resulting matches. 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 matches, cancel this task.

    View Source on GitHub

  • Begins asynchronously calculating routes that match the given options and delivers the results to a closure.

    This method retrieves the routes asynchronously from the Mapbox Map Matching API 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.

    To get the Matches that these routes are based on, use the calculate(_:completionHandler:) method instead.

    Declaration

    Swift

    @discardableResult
@objc(calculateRoutesMatchingOptions:completionHandler:)
open func calculateRoutes(matching options: MatchOptions, completionHandler: @escaping RouteCompletionHandler) -> URLSessionDataTask

    Parameters

    options

    A MatchOptions object specifying the requirements for the resulting match.
    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 GET 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. Alternatively, you can use the calculate(_:options:) method, which automatically sends the request and parses the response.

    Declaration

    Swift

    @objc(URLForCalculatingDirectionsWithOptions:)
open func url(forCalculating options: DirectionsOptions) -> URL

    Parameters

    options

    A DirectionsOptions object specifying the requirements for the resulting routes.

    Return Value

    The URL to send the request to.

    View Source on GitHub

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

    The query part of the URL is generally suitable for GET requests. However, if the URL is exceptionally long, it may be more appropriate to send a POST request to a URL without the query part, relegating the query to the body of the HTTP request. Use the urlRequest(forCalculating:) method to get an HTTP request that is a GET or POST request as necessary.

    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. Alternatively, you can use the calculate(_:options:) method, which automatically sends the request and parses the response.

    Declaration

    Swift

    @objc(URLForCalculatingDirectionsWithOptions:HTTPMethod:)
open func url(forCalculating options: DirectionsOptions, httpMethod: String) -> URL

    Parameters

    options

    A DirectionsOptions object specifying the requirements for the resulting routes.
    httpMethod

    The HTTP method to use. The value of this argument should match the URLRequest.httpMethod of the request you send. Currently, only GET and POST requests are supported by the API.

    Return Value

    The URL to send the request to.

    View Source on GitHub

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

    The returned request is a GET or POST request as necessary to accommodate URL length limits.

    After sending the request returned by this method, you can parse the JSON data in the response and pass it into the Route.init(json:waypoints:profileIdentifier:) initializer. Alternatively, you can use the calculate(_:options:) method, which automatically sends the request and parses the response.

    Declaration

    Swift

    @objc(URLRequestForCalculatingDirectionsWithOptions:)
open func urlRequest(forCalculating options: DirectionsOptions) -> URLRequest

    Parameters

    options

    A DirectionsOptions object specifying the requirements for the resulting routes.

    Return Value

    A GET or POST HTTP request to calculate the specified options.

    View Source on GitHub

  • URL to the endpoint listing available versions

    Declaration

    Swift

    public var availableVersionsURL: URL { get }
    View Source on GitHub

  • URL to the endpoint for downloading a tile pack

    Declaration

    Swift

    public func tilesURL(for coordinateBounds: CoordinateBounds, version: OfflineVersion) -> URL
    View Source on GitHub

  • Fetches the available offline routing tile versions and returns them in descending chronological order. The most recent version should typically be passed into downloadTiles(in:version:completionHandler:).

    Declaration

    Swift

    @discardableResult
public func fetchAvailableOfflineVersions(completionHandler: @escaping OfflineVersionsHandler) -> URLSessionDataTask

    Parameters

    completionHandler

    A closure of type OfflineVersionsHandler which will be called when the request completes
    View Source on GitHub

  • Downloads offline routing tiles of the given version within the given coordinate bounds using the shared URLSession. The tiles are written to disk at the location passed into the completionHandler.

    Declaration

    Swift

    @discardableResult
public func downloadTiles(in coordinateBounds: CoordinateBounds,
                          version: OfflineVersion,
                          completionHandler: @escaping OfflineDownloaderCompletionHandler) -> URLSessionDownloadTask

    Parameters

    coordinateBounds

    The bounding box
    version

    The version to download. Version is represented as a String (yyyy-MM-dd-x)
    completionHandler

    A closure of type OfflineDownloaderCompletionHandler which will be called when the request completes
    View Source on GitHub