Mapbox Directions for Swift

Mapbox Directions for Swift makes it easy to connect your iOS, macOS, tvOS, or watchOS application to the Mapbox Directions and Map Matching APIs. Quickly get driving, cycling, or walking directions, whether the trip is nonstop or it has multiple stopping points, all using a simple interface reminiscent of MapKit’s MKDirections API. Fit a GPX trace to the OpenStreetMap road network. The Mapbox Directions and Map Matching APIs are powered by the OSRM and Valhalla routing engines. For more information, see the Mapbox Navigation homepage.

Mapbox Directions pairs well with MapboxGeocoder.swift, MapboxStatic.swift, the Mapbox Navigation SDK for iOS, and the Mapbox Maps SDK for iOS or macOS SDK.

Installation

Specify the following dependency in your Carthage Cartfile:

github "mapbox/mapbox-directions-swift" ~> 2.15

Or in your CocoaPods Podfile:

pod 'MapboxDirections', '~> 2.15'

Or in your Swift Package Manager Package.swift:

.package(url: "https://github.com/mapbox/mapbox-directions-swift.git", from: "2.15.0")

Then import MapboxDirections.

Configuration

You’ll need a Mapbox access token in order to use the API. If you’re already using the Mapbox Maps SDK for iOS or macOS SDK, Mapbox Directions automatically recognizes your access token, as long as you’ve placed it in the MBXAccessToken key of your application’s Info.plist file.

Starting points

Directions is the main class that represents the Mapbox Directions and Map Matching APIs. To calculate directions between coordinates, configure a RouteOptions object and pass it into Directions.calculate(_:completionHandler:). Similarly, to match a trace to the road network, configure a MatchOptions object and pass it into either Directions.calculate(_:completionHandler:) or Directions.calculateRoutes(matching:completionHandler:). These methods asynchronously send requests to the API, then form Route or Match objects that correspond to the API’s response.

A Route object is composed of one or more RouteLegs between waypoints, which in turn are composed of one or more RouteSteps between maneuvers. Depending on the request, a RouteStep may additionally contain objects representing intersection- and segment-level data. A Match object is structured similarly, except that it provides additional details about how the trace matches the road network.

For further details, consult the guides and examples included with this API reference. To integrate real-time turn-by-turn navigation into your iOS application, see “Navigation SDK”. If you have any questions, please see our help page. We welcome your bug reports, feature requests, and contributions.

Changes in version 2.15.0

  • Decoding an Intersection whose lanes report differing valid_indication values no longer fails. Lanes at the same intersection may legitimately disagree, for example one lane indicating a straight maneuver and an adjacent lane indicating a slight turn.
  • Added Intersection.laneValidIndications, which contains each lane’s own applicable ManeuverDirection, parallel to Intersection.approachLanes.
  • Deprecated Intersection.usableLaneIndication, as well as the Intersection initializer that takes it, in favor of Intersection.laneValidIndications. The deprecated property collapses the lanes to a single value, preferring a preferred lane’s indication, then a usable lane’s, then the first lane’s.
  • An empty valid_indication on a lane now decodes as no indication for that lane instead of failing to decode the route.
  • Added RouteOptions.excludedLocations allowing you to exclude custom locations (such as dangerous entry/exit points, low quality roads, etc.) from routing by coordinate, in addition to the existing road-class-based RouteOptions.roadClassesToAvoid. This experimental feature maps to the Directions API’s beta exclude=point(longitude latitude) parameter and is currently limited to the mapbox/driving and mapbox/driving-traffic profiles, with at most 50 locations per request.
  • Fixed RouteOptions.roadClassesToAvoid/roadClassesToAllow parsing (from a URL or from an archived/persisted RouteOptions) so that a single unrecognized road-class value no longer discards every other recognized value alongside it, and no longer fails decoding the entire RouteOptions object. Surrounding whitespace is now ignored as well, so an exclude or include parameter written the way the Directions API documents it (toll, motorway) is recognized in full.