iOS Developer Library — Prerelease

Developer

MapKit Framework Reference MKMapItem Class Reference

Options
Deployment Target:

On This Page
Language:

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.

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 case, the directions request contains map items with the start and end points to use when creating the directions. The second 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 a map item 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 app, 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 to do this might look like the following:

  1. Class itemClass = [MKMapItem class];
  2. if (itemClass && [itemClass respondsToSelector:@selector(openMapsWithItems:launchOptions:)]) {
  3. // Use class
  4. }
  • Creates and returns a singleton map item object representing the device’s current location.

    Declaration

    Swift

    class func mapItemForCurrentLocation() -> MKMapItem

    Objective-C

    + (MKMapItem * _Nonnull)mapItemForCurrentLocation

    Return Value

    An MKMapItem object representing the current location.

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    init(placemark placemark: MKPlacemark)

    Objective-C

    - (instancetype _Nonnull)initWithPlacemark:(MKPlacemark * _Nonnull)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.

  • The placemark object containing the location information.

    Declaration

    Swift

    var placemark: MKPlacemark { get }

    Objective-C

    @property(nonatomic, readonly) MKPlacemark * _Nonnull 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 YEStrue.

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    var isCurrentLocation: Bool { get }

    Objective-C

    @property(nonatomic, readonly) BOOL isCurrentLocation

    Discussion

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

    Availability

    Available in iOS 6.0 and later.

  • name name Property

    The descriptive name associated with the map item.

    Declaration

    Swift

    var name: String?

    Objective-C

    @property(nonatomic, copy) NSString * _Nullable 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.

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

    Declaration

    Swift

    var phoneNumber: String?

    Objective-C

    @property(nonatomic, copy) NSString * _Nullable 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.

  • url url Property

    The URL associated with the specified location.

    Declaration

    Swift

    var url: NSURL?

    Objective-C

    @property(nonatomic, strong) NSURL * _Nullable 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.

  • Open the Maps app and display the specified map items.

    Declaration

    Swift

    class func openMapsWithItems(_ mapItems: [MKMapItem], launchOptions launchOptions: [String : AnyObject]?) -> Bool

    Objective-C

    + (BOOL)openMapsWithItems:(NSArray<MKMapItem *> * _Nonnull)mapItems launchOptions:(NSDictionary<NSString *,id> * _Nullable)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, a 3D perspective, 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.

    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.

  • Open the Maps app and display this map item.

    Declaration

    Swift

    func openInMapsWithLaunchOptions(_ launchOptions: [String : AnyObject]?) -> Bool

    Objective-C

    - (BOOL)openInMapsWithLaunchOptions:(NSDictionary<NSString *,id> * _Nullable)launchOptions

    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.

    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.

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

    Declaration

    Swift

    let MKLaunchOptionsDirectionsModeKey: String let MKLaunchOptionsMapTypeKey: String let MKLaunchOptionsMapCenterKey: String let MKLaunchOptionsMapSpanKey: String let MKLaunchOptionsShowsTrafficKey: String let MKLaunchOptionsCameraKey: String

    Objective-C

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

    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 iOS 6.0 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, or hybrid) to display.

      Available in iOS 6.0 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 iOS 6.0 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 iOS 6.0 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.

      Available in iOS 6.0 and later.

    • MKLaunchOptionsCameraKey

      MKLaunchOptionsCameraKey

      The value of this key is an MKMapCamera object that describes a virtual camera that can specify a 3D perspective for the map. If you do not specify this key, Maps uses its current settings to define the appearance of the map.

      Available in iOS 7.1 and later.

    Discussion

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

  • Strings representing the possible values of the MKLaunchOptionsDirectionsModeKey key.

    Declaration

    Swift

    let MKLaunchOptionsDirectionsModeDriving: String let MKLaunchOptionsDirectionsModeWalking: String

    Objective-C

    NSString * const MKLaunchOptionsDirectionsModeDriving; NSString * const MKLaunchOptionsDirectionsModeWalking;

    Constants

    • MKLaunchOptionsDirectionsModeDriving

      MKLaunchOptionsDirectionsModeDriving

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

      Available in iOS 6.0 and later.

    • MKLaunchOptionsDirectionsModeWalking

      MKLaunchOptionsDirectionsModeWalking

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

      Available in iOS 6.0 and later.