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
Parameters
waypoints
An array of
Waypoint
objects. Each waypoint object corresponds to aWaypoint
object in the originalRouteOptions
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 theRouteOptions
object’sincludesAlternativeRoutes
property was set totrue
. The preferred route depends on the route options object’sprofileIdentifier
property.error
The error that occurred, or
nil
if the placemarks were obtained successfully. -
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.
-
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
-
The API endpoint to use when requesting directions.
Declaration
Swift
@objc public private(set) var apiEndpoint: URL
-
The Mapbox access token to associate with the request.
Declaration
Swift
@objc public let accessToken: String
-
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.
-
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.
-
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.
-
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
Route
s based on these matches, use thecalculateRoutes(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.
-
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
Match
es that these routes are based on, use thecalculate(_: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.
-
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 thecalculate(_: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.
-
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 thecalculate(_: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.
-
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 thecalculate(_: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.
-
URL to the endpoint listing available versions
Declaration
Swift
public var availableVersionsURL: URL { get }
-
URL to the endpoint for downloading a tile pack
Declaration
Swift
public func tilesURL(for coordinateBounds: CoordinateBounds, version: OfflineVersion) -> URL
-
Fetch the available versions in descending chronological order. A version is represented as a String (yyyy-MM-dd or yyyy-MM-dd-x).
Declaration
Swift
@discardableResult @objc public func fetchAvailableOfflineVersions(completionHandler: @escaping OfflineVersionsHandler) -> URLSessionDataTask
Parameters
completionHandler
The closure to call with the results
Return Value
A
URLSessionDataTask
-
Initializes an
URLSessionDownloadTask
used for downloading tiles within a given bounding box.Declaration
Swift
@discardableResult @objc public func downloadTiles(in coordinateBounds: CoordinateBounds, version: OfflineVersion, session: URLSession? = URLSession.shared, completionHandler: @escaping OfflineDownloaderCompletionHandler) -> URLSessionDownloadTask
Parameters
coordinateBounds
The bounding box
version
The version to download. Version is represented as a String (yyyy-MM-dd-x)
session
Optional URLSession
completionHandler
The closure to call with the results
Return Value
A
URLSessionDownloadTask