iOS Developer Library — Pre-Release

Developer

MapKit Framework Reference MKDirections Class Reference

Options
Deployment Target:

On This Page
Language:

MKDirections

An MKDirections object provides you with route-based directions data from Apple servers. You can use instances of this class to get travel-time information or driving or walking directions based on the data in an MKDirectionsRequest object that you provide. The directions object passes your request to the Apple servers and returns the requested information to a block that you provide.

Each directions object handles a single request for directions, although you can cancel and restart that request as needed. You can create multiple instances of this class and process different route requests at the same time, but you should make requests only when you plan to present the corresponding route information to the user. Apps may receive a MKErrorLoadingThrottled error if too many requests have been made from the current device in too short a time period.

Inheritance


Conforms To


Import Statement


Swift

import MapKit

Objective-C

@import MapKit;

Availability


Available in iOS 7.0 and later.
  • init(request:) - initWithRequest: Designated Initializer

    Initializes and returns a directions object using the specified request.

    Declaration

    Swift

    init!(request request: MKDirectionsRequest!)

    Objective-C

    - (instancetype)initWithRequest:(MKDirectionsRequest *)request

    Parameters

    request

    The request object containing the start and end points of the route. This parameter must not be nil.

    Return Value

    An initialized directions object.

    Discussion

    After initializing your directions object, you must call the calculateDirectionsWithCompletionHandler: or calculateETAWithCompletionHandler: method to perform the request.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

  • Begins calculating the requested route information asynchronously.

    Declaration

    Swift

    func calculateDirectionsWithCompletionHandler(_ completionHandler: MKDirectionsHandler!)

    Objective-C

    - (void)calculateDirectionsWithCompletionHandler:(MKDirectionsHandler)completionHandler

    Parameters

    completionHandler

    The block to execute when the directions are ready or when an error occurs. This parameter must not be nil.

    Discussion

    This method initiates the request for directions and calls your completion handler block with the results. Your completion handler is executed on your app’s main thread. The implementation of your handler should check for errors and then incorporate the response data as appropriate.

    If you call this method while a previous request is in process, this method calls your completion handler with an error. You can determine if a request is in process by checking the value of the calculating property. You can also cancel a request as needed.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

  • Begins calculating the requested travel-time information asynchronously.

    Declaration

    Swift

    func calculateETAWithCompletionHandler(_ completionHandler: MKETAHandler!)

    Objective-C

    - (void)calculateETAWithCompletionHandler:(MKETAHandler)completionHandler

    Parameters

    completionHandler

    The block to execute when the travel-time estimate is ready or when an error occurs. This parameter must not be nil.

    Discussion

    This method initiates a request for a travel-time estimate and calls your completion handler block with the results. Travel-time estimates take much less time to generate than directions, so use this method in situations where you want a time estimate only. Your completion handler is executed on your app’s main thread. The implementation of your handler should check for errors and then incorporate the response data as appropriate.

    If you call this method while a previous request is in process, this method calls your completion handler with an error. You can determine if a request is in process by checking the value of the calculating property. You can also cancel a request as needed.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

  • Cancels a pending request.

    Declaration

    Swift

    func cancel()

    Objective-C

    - (void)cancel

    Discussion

    After canceling a request, you can call the calculateDirectionsWithCompletionHandler: method again (if you want) to restart the request process.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

  • A Boolean value indicating whether a request is currently in process. (read-only)

    Declaration

    Swift

    var calculating: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isCalculating) BOOL calculating

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

Data Types

  • The block to use for processing the requested route information.

    Declaration

    Swift

    typealias MKDirectionsHandler = (MKDirectionsResponse!, NSError!) -> Void

    Objective-C

    typedef void (^MKDirectionsHandler)(MKDirectionsResponse *response, NSError *error);

    Discussion

    This block takes two parameters:

    • The response parameter contains the route information for the request. If an error occurred or no route could be determined, this parameter is nil.

    • The error parameter contains information about any errors that occurred. If no errors occurred, this parameter is nil.

    The implementation of your block should check for a value in the error parameter and, if that parameter is nil, incorporate the route information provided in the response parameter.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

  • The block to use for processing travel-time information.

    Declaration

    Swift

    typealias MKETAHandler = (MKETAResponse!, NSError!) -> Void

    Objective-C

    typedef void (^MKETAHandler)(MKETAResponse *response, NSError *error);

    Discussion

    This block takes two parameters:

    • The response parameter contains the travel time response. If an error occurred or no travel time could be determined, this parameter is nil.

    • The error parameter contains information about any errors that occurred. If no errors occurred, this parameter is nil.

    The implementation of your block should check for a value in the error parameter and, if that parameter is nil, incorporate the travel-time information provided in the response parameter.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.