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" ~> 0.31
Or in your CocoaPods Podfile:
pod 'MapboxDirections', '~> 0.31'
Or in your Swift Package Manager Package.swift:
.package(url: "https://github.com/mapbox/mapbox-directions-swift.git", from: "0.30.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 MGLMapboxAccessToken
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 RouteLeg
s between waypoints, which in turn are composed of one or more RouteStep
s 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 0.31.0
Packaging
- Renamed MapboxDirections.swift to Mapbox Directions for Swift. The CocoaPods pod is now named MapboxDirections, matching the module name. (#400)
- This library now requires a minimum deployment target of iOS 10.0 or above, macOS 10.12.0 or above, tvOS 10.0 or above, or watchOS 3.0 or above. Older operating system versions are no longer supported. (#379)
- Swift is now required to directly use public types and methods defined by this library. If your application is written in Objective-C or Cocoa-AppleScript, you need to implement your own wrapper in Swift that bridges to Objective-C. (#382)
- This library now depends on Turf. (#382)
Error handling
- The
RouteCompletionHandler
andMatchCompletionHandler
closures’error
argument is now aDirectionsError
instead of anNSError
. (#382) - Classes such as
Route
,Match
, andRouteStep
conform to theCodable
protocol, so you can create instances of them from JSON-formattedData
usingJSONDecoder
and round-trip them back to JSON usingJSONEncoder
. Malformed input now throws decoding errors instead of crashing by unwrappingnil
s. (#382)
Visual instructions
- Removed the
Lane
class in favor of storing an array ofLaneIndication
s directly in theIntersection.approachLanes
property. (#382) - Removed the
ComponentRepresentable
protocol,VisualInstructionComponent
class, andLaneIndicationComponent
class in favor of aVisualInstruction.Component
enumeration that contains aVisualInstruction.Component.TextRepresentation
and/orVisualInstruction.Component.ImageRepresentation
, depending on the type of component. (#382) - Added the
VisualInstruction.Component.ImageRepresentation.imageURL(scale:format:)
method for fetching images with scales other than the current screen’s native scale or formats other than PNG. (#382)
Other changes
- Removed support for Mapbox Directions API v4. (#382)
- Replaced the
MBDefaultWalkingSpeed
,MBMinimumWalkingSpeed
, andMBMaximumWalkingSpeed
constants withCLLocationSpeed.normalWalking
,CLLocationSpeed.minimumWalking
, andCLLocationSpeed.maximumWalking
, respectively. - Replaced the
Route.coordinates
property withRoute.shape
and theRouteStep.coordinates
property withRouteStep.shape
. TheRoute.coordinateCount
andRouteStep.coordinateCount
properties have been removed, but you can use theLineString.coordinates
property to get the array ofCLLocationCoordinate2D
s. (#382) RouteLeg.source
andRouteLeg.destination
are now optional. They can benil
when theRouteLeg
object is decoded individually from JSON. (#382)- Removed
TransportType.none
,ManeuverType.none
, andManeuverDirection.none
. UnrecognizedTransportType
andManeuverDirection
values now raise decoding errors. (#382) RouteStep.maneuverType
is now optional. (#382)- Renamed the
Tracepoint.alternateCount
property toTracepoint.countOfAlternatives
. (#382) - The
Intersection.approachIndex
andIntersection.outletIndex
properties are now optional, not −1, in the case of a departure or arrival maneuver. (#393) - Added initializers for
Route
,Match
,RouteLeg
, andRouteStep
. (#393) - Various properties of
Route
,RouteLeg
, andRouteStep
are now writable. (#393) - Added
AttributeOptions.maximumSpeedLimit
for getting maximum posted speed limits in theRouteLeg.segmentMaximumSpeedLimits
property. (#367) - Added the
RouteLeg.segmentRangesByStep
property for more easily associatingRouteStep
s with the values in segment-based arrays such asRouteLeg.segmentCongestionLevels
. (#367) - The
RouteOptions.alleyPriority
property now works withDirectionsProfileIdentifier.automobile
, allowing you to request routes that prefer or avoid alleys while driving. (#416)