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.

Creating a Directions Object

  • 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
    View Source on GitHub

  • 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
    View Source on GitHub

  • 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.
    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.

    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.

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

  • 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 to true 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 the RouteResponse 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.

    View Source on GitHub

  • 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 to true 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 the RouteResponse 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.

    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

    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

    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

    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

  • The URL to a list of available versions.

    Declaration

    Swift

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

  • 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.

    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: 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
    View Source on GitHub