Directions

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.

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

  • Creates a new instance of Directions object.

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.

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

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

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

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

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

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

  • The URL to a list of available versions.

  • Returns the URL to generate and download a tile pack from the Route Tiles API.

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

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