MKDirections Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/MapKit.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
MKDirections.h

Overview

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.

Tasks

Initializing a Directions Object

Getting the Directions

Properties

calculating

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

@property (nonatomic, readonly, getter=isCalculating) BOOL calculating
Availability
  • Available in iOS 7.0 and later.
Declared In
MKDirections.h

Instance Methods

calculateDirectionsWithCompletionHandler:

Begins calculating the requested route information asynchronously.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
MKDirections.h

calculateETAWithCompletionHandler:

Begins calculating the requested travel-time information asynchronously.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
MKDirections.h

cancel

Cancels a pending request.

- (void)cancel
Discussion

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

Availability
  • Available in iOS 7.0 and later.
Declared In
MKDirections.h

initWithRequest:

Initializes and returns a directions object using the specified request.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
MKDirections.h

Constants

MKDirectionsHandler

The block to use for processing the requested route information.

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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKDirections.h

MKETAHandler

The block to use for processing travel-time information.

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.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKDirections.h