MKMapItem Class Reference

Inherits from	NSObject
Conforms to	NSObject (NSObject)
Framework	/System/Library/Frameworks/MapKit.framework
Availability	Available in iOS 6.0 and later.
Companion guide	Location Awareness Programming Guide
Declared in	MKMapItem.h

Overview

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.

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:

Class itemClass = [MKMapItem class];

if (itemClass && [itemClass respondsToSelector:@selector(openMapsWithItems:launchOptions:)]) {

   // Use class

Tasks

Creating and Initializing Map Items

Accessing the Map Item Attributes

Launching the Maps App

Properties

isCurrentLocation

A Boolean value indicating whether the map item represents the user’s current location.

@property (nonatomic, readonly) BOOL isCurrentLocation

Discussion

If the value of this property is YES, the map item represents the user’s current location. If YES, the value in the placemark property is set to nil.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

name

The descriptive name associated with the map item.

@property (nonatomic, copy) NSString *name

Discussion

Use this property to specify the name associated with the location. For example, if there is a business at the specified location, you would use this property to specify the name of the business.

If this map item represents the user’s current location, the value in property is set to a localized version of “Current Location”.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

phoneNumber

The phone number associated with a business at the specified location.

@property (nonatomic, copy) NSString *phoneNumber

Discussion

If there is a relevant phone number associated with the location, such as a phone number for a business at the location, use this property to specify that value.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

placemark

The placemark object containing the location information.

@property (nonatomic, readonly, retain) MKPlacemark *placemark

Discussion

If you created the map item using the mapItemForCurrentLocation method, the value of this property is nil and the isCurrentLocation property is set to YES.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

url

The URL associated with the specified location.

@property (nonatomic, retain) NSURL *url

Discussion

If there is a relevant URL associated with the location, such as a URL for a business at the location, use this property to specify that value.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

Class Methods

mapItemForCurrentLocation

Creates and returns a singleton map item object representing the device’s current location.

+ (MKMapItem *)mapItemForCurrentLocation

Return Value

An MKMapItem object representing the current location.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

openMapsWithItems:launchOptions:

Open the Maps app and display the specified map items.

+ (BOOL)openMapsWithItems:(NSArray *)mapItems launchOptions:(NSDictionary *)launchOptions

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

YES if the map items were successfully opened by the Maps app, or NO 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.

If you do not include the MKLaunchOptionsMapCenterKey and MKLaunchOptionsMapSpanKey keys in your launchOptions dictionary, Maps constructs a region that encompasses the provided items. It uses this region to set the visible portion of the map.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

Instance Methods

initWithPlacemark:

Initializes and returns a map item object using the specified placemark object.

- (id)initWithPlacemark:(MKPlacemark *)placemark

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.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

openInMapsWithLaunchOptions:

Open the Maps app and display this map item.

- (BOOL)openInMapsWithLaunchOptions:(NSDictionary *)launchOptions

Parameters

launchOptions

This parameter may be nil.

Return Value

YES if this map item was successfully opened by the Maps app, or NO 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.

If you do not include the MKLaunchOptionsMapCenterKey and MKLaunchOptionsMapSpanKey keys in your launchOptions dictionary, Maps constructs a region around the current item. It uses that region to set the visible portion of the map.

Availability

Available in iOS 6.0 and later.

Declared In

MKMapItem.h

Constants

Launch Options Dictionary Keys

Launch options to specify when opening map items in the Maps app.

NSString * const MKLaunchOptionsDirectionsModeKey;
NSString * const MKLaunchOptionsMapTypeKey;
NSString * const MKLaunchOptionsMapCenterKey;
NSString * const MKLaunchOptionsMapSpanKey;
NSString * const MKLaunchOptionsShowsTrafficKey;

Constants

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 iOS 6.0 and later.

Declared in MKMapItem.h.

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 iOS 6.0 and later.

Declared in MKMapItem.h.

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 iOS 6.0 and later.

Declared in MKMapItem.h.

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 iOS 6.0 and later.

Declared in MKMapItem.h.

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.

Available in iOS 6.0 and later.

Declared in MKMapItem.h.

Discussion

You specify these keys in the launch options dictionary for the openMapsWithItems:launchOptions: or openInMapsWithLaunchOptions: method.

Directions Mode Values

Strings representing the possible values of the MKLaunchOptionsDirectionsModeKey key.

NSString * const MKLaunchOptionsDirectionsModeDriving;
NSString * const MKLaunchOptionsDirectionsModeWalking;

Constants

MKLaunchOptionsDirectionsModeDriving

Tells the Maps app to display driving directions between the start and end points.

Available in iOS 6.0 and later.

Declared in MKMapItem.h.

MKLaunchOptionsDirectionsModeWalking

Tells the Maps app to display walking directions between the start and end points.

Available in iOS 6.0 and later.

Declared in MKMapItem.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.