MKMapItem

The MKMapItem class encapsulates information about a specific point on a map. This information includes the map location and any other data that might be relevant, such as the name of a business at that location. Apps use this class to share map-related data with the Maps app.
More...

You use this class in one of two ways. If your app is able to display point-to-point directions, the Maps app can send a directions request to your app in response to a request by the user to use your app for routing. In that instance, the directions request contains map items with the start and end points to use when creating the directions. The other way to use map items is to create them in your app and then ask the Maps app to display them. For example, if your app allows the user to search for local businesses or points of interest, you can create map items for each location and ask Maps to display pins at the corresponding locations.

Usually, you use this class to represent fixed locations on the map, but you can also use the mapItemForCurrentLocation method to get a map item that represents the user’s current location. For privacy reasons, and because the user’s location can change, the map item returned by that method does not contain any coordinate data. When you need the actual location of the user, you must use the Core Location framework to retrieve it.

Usage Special Considerations

To determine whether a class is available at runtime in a given iOS release, you typically check whether that class is nil. Unfortunately, this test is not cleanly accurate for MKMapItem. Although this class was publicly available starting with iOS 6.0, it was in development prior to that. Although the class exists in earlier releases, you should not attempt to use it in those releases.

To determine at runtime whether you can use map items in your application, test whether the class and the openMapsWithItems:launchOptions: class method exist. That method was not added to the class until iOS 6.0. The code might look like the following:

Declaration

Parameters

placemark

The placemark object corresponding to the desired map location. This parameter must not be nil.

Return Value

An initialized map item object.

Discussion

Use this method to create a map item for an existing placemark. Do not use it to create a map item representing the user’s current location. To do that, use the mapItemForCurrentLocation method instead.

Parameters

mapItems

An array containing one or more MKMapItem objects representing the items you want to display on the map. This parameter may be nil.

launchOptions

Additional information that the Maps app can use to configure the map display. For example, you can use the launch options to specify the visible map region and the map type. For a list of keys you can put into this dictionary, see “Launch Options Dictionary Keys”.

You may specify nil for this parameter.

Return Value

YEStrue if the map items were successfully opened by the Maps app, or NOfalse if there was an error.

Discussion

You use this method to pass one or more map items to the Maps app. For example, you might use this method to ask the Maps app to display location-based search results generated by your app. Maps displays pins at each location you specify and uses the contents of each map item object to display additional information.

If you specify the MKLaunchOptionsDirectionsModeKey option in the launchOptions dictionary, the mapItems array must have no more than two items in it. If the array contains one item, the Maps app generates directions from the user’s current location to the location specified by the map item. If the array contains two items, the Maps app generates directions from the location of the first item to the location of the second item in the array.

Declaration

Parameters

launchOptions

Additional information that the Maps app can use to configure the map display. For example, you can use the launch options to specify the visible map region and the map type. For a list of keys you can put into this dictionary, see “Launch Options Dictionary Keys”.

This parameter may be nil.

Return Value

YEStrue if this map item was successfully opened by the Maps app, or NOfalse if there was an error.

Discussion

You use this method to pass the current map item to the Maps app. If your map item contains descriptive information about the location (such as a name or URL), the Maps app displays that information at the specified coordinate.

If you specify the MKLaunchOptionsDirectionsModeKey option in the launchOptions dictionary, the Maps app interprets that as an attempt to map from the user’s current location to the location specified by this map item.

Constants

MKLaunchOptionsDirectionsModeKey

MKLaunchOptionsDirectionsModeKey

The value of this key is an NSString corresponding to one of the values described in “Directions Mode Values”. You specify this key to tell the Maps app to treat the provided map items as start and end points for routing directions. If this key is not present, Maps displays pins at the specified locations.

Available in OS X v10.9 and later.

MKLaunchOptionsMapTypeKey

MKLaunchOptionsMapTypeKey

The value of this key is an NSNumber object whose value is an integer corresponding to an MKMapType value. This value represents the type of map (standard, satellite, hybrid) to display.

Available in OS X v10.9 and later.

MKLaunchOptionsMapCenterKey

MKLaunchOptionsMapCenterKey

The value of this key is an NSValue object that contains an encoded CLLocationCoordinate2D structure. This value represents the location on which the map view should be centered.

Available in OS X v10.9 and later.

MKLaunchOptionsMapSpanKey

MKLaunchOptionsMapSpanKey

The value of this key is an NSValue object that contains an encoded MKCoordinateSpan structure. This value represents the region that the map view should display.

Available in OS X v10.9 and later.

MKLaunchOptionsShowsTrafficKey

MKLaunchOptionsShowsTrafficKey

The value of this key is an NSNumber object that contains a Boolean value. This value indicates whether traffic information should be displayed on the map. If you do not specify this key, Maps uses its current settings to determine whether or not to display traffic.