Providing Directions

Configuring Your App to Accept Direction Requests

To enable directions support for your app, you must configure the following support for your app target in Xcode:

• Enable routing requests and specify the types of directions your app is capable of providing.

• Configure a special document type to handle incoming routing requests.

You enable routing request support using the Accept transit routing requests checkbox in the Maps section of your target’s Summary tab. As part of enabling directions, you must specify the types of directions (pedestrian, car, subway, and so on) your app is able to provide. Enabling directions support adds the MKDirectionsApplicationSupportedModes key to your app’s Info.plist file and sets the value of that key to the transportation modes you select. You must also provide a GeoJSON file containing the regions for which your app is capable of providing directions. (For information about specifying the GeoJSON file, see “Declaring the Supported Geographic Coverage for Directions.”)

In addition to declaring the types of directions your app supports, you need to add a document type to your project whose purpose is to handle incoming routing requests. To add the document type, use the Xcode document type editor, located in the Info tab of your target. Create the new type and use the information in Table 6-1 to set the values for the type. You should use the values in the table exactly as they appear here.

The changes you make in the document types editor cause Xcode to add a corresponding entry to the CFBundleDocumentTypes key in your app’s Info.plist file. For more information about your app’s Info.plist file and the keys you put into it, see Information Property List Key Reference.

Declaring the Supported Geographic Coverage for Directions

Apps must declare the geographic regions for which they are capable of providing directions. Declaring the supported regions prevents the system from sending requests that your app is unable to handle. For example, if your app provides subway route information only for New York, you would not want it to receive requests to provide directions in London.

To declare your app’s supported regions, you must create a GeoJSON file, which is a type of JavaScript Object Notation (JSON) file. This is your app’s geographic coverage file and it contains a set of map coordinates that define the boundaries of one or more geographic regions. The format of this file is part of a public specification, the details of which you can obtain at http://geojson.org/geojson-spec.html.

Your geographic coverage file is used by the Maps app and the App Store, but not by your app. Uploading it to iTunes Connect makes it possible for Maps to look up apps on the App Store that are capable of providing directions in the target region. It can then provide the user with that information in case the user wants to download one of those apps. Because you upload it to iTunes Connect, you can also update the file at any time without submitting a new version of your app.

{ "type": "MultiPolygon",

  "coordinates": [

    [[[-122.7, 37.3], [-121.9, 37.3], [-121.9, 37.9], [-122.7, 37.9], [-122.7, 37.3]]],

    [[[-87.9, 41.5], [-87.3, 41.5], [-87.3, 42.1], [-87.9, 42.1], [-87.9, 41.5]]]

    ]

}

Handling Direction Requests

The system sends direction requests to your app using URLs. When the user asks the Maps app for directions and chooses your app, Maps creates a URL with the start and end points and asks your app to open it. You handle the opening of this URL in your app’s application:openURL:sourceApplication:annotation: method, just like you would for other URLs. But the steps you take to process the URL are a little more prescribed.

When your app receives a URL to open, it should perform the following steps in its application:openURL:sourceApplication:annotation: method:

1. Call the isDirectionsRequestURL: class method of MKDirectionsRequest to check whether the URL is a directions request URL. If it is a directions request, proceed with the remaining steps.

2. Create an MKDirectionsRequest object using the provided URL.

3. Obtain the start and end points of the route from the MKDirectionsRequest object.

   The start and end points are specified as MKMapItem objects, which contain the geographic coordinate of the location and possibly additional information. If the MKMapItem object represents the user’s current location, you need to use Core Location to retrieve the actual coordinate location data yourself.

4. Compute and display the route using your custom routing technology.

Because the preceding steps are the same for every app, you can include code in your application:openURL:sourceApplication:annotation: method similar to that shown in Listing 6-3. The most important addition you must make is to compute the route information and display it in your app. If your app handles other URL types, you would also include code for processing those URLs separately.

Listing 6-3  Handling a directions request URL

- (BOOL)application:(UIApplication *)application

           openURL:(NSURL *)url

           sourceApplication:(NSString *)sourceApplication

           annotation:(id)annotation {

   if ([MKDirectionsRequest isDirectionsRequestURL:url]) {

      MKDirectionsRequest* directionsInfo = [[MKDirectionsRequest alloc] initWithContentsOfURL:url];

      // TO DO: Plot and display the route using the

      //   source and destination properties of directionsInfo.

      return YES;

   }

   else {

    // Handle other URL types...

   }

    return NO;

}

For additional information about using the MKDirectionsRequest class, see MKDirectionsRequest Class Reference.