Directions
open class Directions : NSObject
extension Directions: OfflineDirectionsProtocol
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 tuple type representing the direction session that was generated from the request.
Declaration
Swift
public typealias Session = (options: DirectionsOptions, credentials: Credentials)
Parameters
options
A
DirectionsOptions
object representing the request parameter options.credentials
A object containing the credentials used to make the request.
-
A closure (block) to be called when a directions request is complete.
Declaration
Swift
public typealias RouteCompletionHandler = (_ session: Session, _ result: Result<RouteResponse, DirectionsError>) -> Void
Parameters
session
A
Directions.Session
object containing session informationresult
A
Result
enum that represents theRouteResponse
if the request returned successfully, or the error if it did not. -
A closure (block) to be called when a map matching request is complete.
Declaration
Swift
public typealias MatchCompletionHandler = (_ session: Session, _ result: Result<MapMatchingResponse, DirectionsError>) -> Void
Parameters
session
A
Directions.Session
object containing session informationresult
A
Result
enum that represents theMapMatchingResponse
if the request returned successfully, or the error if it did not. -
A closure (block) to be called when a directions refresh request is complete.
Postcondition
To update the original route, pass
RouteRefreshResponse.route
into theRoute.refreshLegAttributes(from:)
,Route.refreshLegIncidents(from:)
,Route.refreshLegClosures(from:legIndex:legShapeIndex:)
orRoute.refresh(from:refreshParameters:)
methods.Declaration
Swift
public typealias RouteRefreshCompletionHandler = (_ credentials: Credentials, _ result: Result<RouteRefreshResponse, DirectionsError>) -> Void
Parameters
credentials
An object containing the credentials used to make the request.
result
A
Result
enum that represents theRouteRefreshResponse
if the request returned successfully, or the error if it did not.
-
The shared directions object.
To use this object, a Mapbox access token should be specified in the
MBXAccessToken
key in the main application bundle’s Info.plist.Declaration
Swift
public static let shared: Directions
-
The Authorization & Authentication credentials that are used for this service.
If nothing is provided, the default behavior is to read credential values from the developer’s Info.plist.
Declaration
Swift
public let credentials: Credentials
-
Creates a new instance of Directions object.
Declaration
Swift
public init(credentials: Credentials = .init(), urlSession: URLSession = .shared, processingQueue: DispatchQueue = .global(qos: .userInitiated))
Parameters
credentials
Credentials that will be used to make API requests to Mapbox Directions API.
urlSession
URLSession that will be used to submit API requests to Mapbox Directions API.
processingQueue
A DispatchQueue that will be used for CPU intensive work.
-
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.
Declaration
Swift
@discardableResult 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 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 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.
-
Begins asynchronously refreshing the route with the given identifier, optionally starting from an arbitrary leg along the route.
This method retrieves skeleton route data asynchronously from the Mapbox Directions Refresh 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.
Precondition
Set
RouteOptions.refreshingEnabled
totrue
when calculating the original route.Declaration
Swift
@discardableResult open func refreshRoute(responseIdentifier: String, routeIndex: Int, fromLegAtIndex startLegIndex: Int = 0, completionHandler: @escaping RouteRefreshCompletionHandler) -> URLSessionDataTask?
Parameters
responseIdentifier
The
RouteResponse.identifier
value of theRouteResponse
that contains the route to refresh.routeIndex
The index of the route to refresh in the original
RouteResponse.routes
array.startLegIndex
The index of the leg in the route at which to begin refreshing. The response will omit any leg before this index and refresh any leg from this index to the end of the route. If this argument is omitted, the entire route is refreshed.
completionHandler
The closure (block) to call with the resulting skeleton route data. 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 skeleton routes, cancel this task.
-
refreshRoute(responseIdentifier:routeIndex:fromLegAtIndex:currentRouteShapeIndex:completionHandler:)
Begins asynchronously refreshing the route with the given identifier, optionally starting from an arbitrary leg and point along the route.
This method retrieves skeleton route data asynchronously from the Mapbox Directions Refresh 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.
Precondition
Set
RouteOptions.refreshingEnabled
totrue
when calculating the original route.Declaration
Swift
@discardableResult open func refreshRoute(responseIdentifier: String, routeIndex: Int, fromLegAtIndex startLegIndex: Int = 0, currentRouteShapeIndex: Int, completionHandler: @escaping RouteRefreshCompletionHandler) -> URLSessionDataTask?
Parameters
responseIdentifier
The
RouteResponse.identifier
value of theRouteResponse
that contains the route to refresh.routeIndex
The index of the route to refresh in the original
RouteResponse.routes
array.startLegIndex
The index of the leg in the route at which to begin refreshing. The response will omit any leg before this index and refresh any leg from this index to the end of the route. If this argument is omitted, the entire route is refreshed.
currentRouteShapeIndex
The index of the route geometry at which to begin refreshing. Indexed geometry must be contained by the leg at
startLegIndex
.completionHandler
The closure (block) to call with the resulting skeleton route data. 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 skeleton 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
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
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
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.
-
The URL to a list of available versions.
Declaration
Swift
public var availableVersionsURL: URL { get }
-
Returns the URL to generate and download a tile pack from the Route Tiles API.
Declaration
Swift
public func tilesURL(for coordinateBounds: BoundingBox, version: OfflineVersion) -> URL
Parameters
coordinateBounds
The coordinate bounds that the tiles should cover.
version
A version obtained from
availableVersionsURL
.Return Value
The URL to generate and download the tile pack that covers the coordinate bounds.
-
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 -
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: BoundingBox, 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