MKMapView

An MKMapView object provides an embeddable map interface, similar to the one provided by the Maps application. You use this class as-is to display map information and to manipulate the map contents from your application. You can center the map on a given coordinate, specify the size of the area you want to display, and annotate the map with custom information.

Important

In iOS 5.1 and earlier, the Map Kit framework uses the Google Mobile Maps (GMM) service to provide map data. Use of specific classes of this framework (and their associated interfaces) is subject to the Google Mobile Maps terms of service. You can find these terms of service at http://code.google.com/apis/maps/iphone/terms.html.

When you initialize a map view, you should specify the initial region for that map to display. You do this by setting the region property of the map. A region is defined by a center point and a horizontal and vertical distance, referred to as the span. The span defines how much of the map at the given point should be visible and is also how you set the zoom level. Specifying a large span results in the user seeing a wide geographical area and corresponds to a low zoom level. Specifying a small span results in the user seeing a more narrow geographical area and corresponds to a higher zoom level.

In addition to setting the span programmatically, the MKMapView class supports many standard interactions for changing the position and zoom level of the map. In particular, map views support flick and pinch gestures for scrolling around the map and zooming in and out. Support for these gestures is enabled by default but can also be disabled using the scrollEnabled and zoomEnabled properties.

You can also use projected map coordinates instead of regions to specify some values. When you project the curved surface of the globe onto a flat surface, you get a two-dimensional version of a map where longitude lines appear to be parallel. To specify locations and distances, you use the MKMapPoint, MKMapSize, and MKMapRect data types.

Although you should not subclass the MKMapView class itself, you can get information about the map view’s behavior by providing a delegate object. The map view calls the methods of your custom delegate to let it know about changes in the map status and to coordinate the display of custom annotations, which are described in more detail in Annotating the Map. The delegate object can be any object in your application as long as it conforms to the MKMapViewDelegate protocol. For more information about implementing the delegate object, see MKMapViewDelegate Protocol Reference.

Annotating the Map

The MKMapView class supports the ability to annotate the map with custom information. Because a map may have potentially large numbers of annotations, map views differentiate between the annotation objects used to manage the annotation data and the view objects for presenting that data on the map.

An annotation object is any object that conforms to the MKAnnotation protocol. Annotation objects are typically implemented using existing classes in your application’s data model. This allows you to manipulate the annotation data directly but still make it available to the map view. Each annotation object contains information about the annotation’s location on the map along with descriptive information that can be displayed in a callout.

The presentation of annotation objects on the screen is handled by an annotation view, which is an instance of the MKAnnotationView class. An annotation view is responsible for presenting the annotation data in a way that makes sense. For example, the Maps application uses a pin icon to denote specific points of interest on a map. (The Map Kit framework offers the MKPinAnnotationView class for similar annotations in your own applications.) You could also create annotation views that cover larger portions of the map.

Because annotation views are needed only when they are onscreen, the MKMapView class provides a mechanism for queueing annotation views that are not in use. Annotation views with a reuse identifier can be detached and queued internally by the map view when they move offscreen. This feature improves memory use by keeping only a small number of annotation views in memory at once and by recycling the views you do have. It also improves scrolling performance by alleviating the need to create new views while the map is scrolling.

When configuring your map interface, you should add all of your annotation objects right away. The map view uses the coordinate data in each annotation object to determine when the corresponding annotation view needs to appear onscreen. When an annotation moves onscreen, the map view asks its delegate to create a corresponding annotation view. If your application has different types of annotations, it can define different annotation view classes to represent each type.

Adding Overlays to the Map

You can use overlays to layer content over a wide portion of the map. An overlay object is any object that conforms to the MKOverlay protocol. An overlay object is a data object that contains the points needed to specify the shape and size of the overlay and its location on the map. Overlays can represent shapes such as circles, rectangles, multi-segment lines, and simple or complex polygons. You can also define your own custom overlays to represent other shapes.

In iOS 7 and later, the presentation of an overlay is handled by an overlay renderer object, which is an instance of the MKOverlayRenderer class. The job of the renderer is to draw the overlay’s content onto the screen when asked to do so by the map view. For example, if you have a simple overlay that represents a bus route, you could use a polyline renderer to draw the line segments that trace the route of the bus. You could also define a custom renderer that draws both the bus route and icons at the location of each bus stop. When specifying overlays, you can add them to specific levels of the map, which allows them to be rendered above or below other types of map content. Prior to iOS 7, overlays are drawn on onscreen using overlay views, which are instances of the MKOverlayView class.

When configuring your map interface, you can add overlay objects at any time. The map view uses the data in each overlay object to determine when the corresponding overlay view needs to appear onscreen. When an overlay moves onscreen, the map view asks its delegate to create a corresponding overlay renderer.

Declaration

Discussion

Changing the value in this property may cause the receiver to begin loading new map content. For example, changing from MKMapTypeStandard to MKMapTypeSatellite might cause it to begin loading the satellite imagery needed for the map. If new data is needed, however, it is loaded asynchronously and appropriate messages are sent to the receiver’s delegate indicating the status of the operation.

Import Statement

Availability

A Boolean value that determines whether the user may use pinch gestures to zoom in and out of the map.

Declaration

Swift

var zoomEnabled: Bool

Objective-C

@property(nonatomic,getter=isZoomEnabled)BOOLzoomEnabled

Discussion

This property controls only user interactions with the map. If you set the value of this property to NOfalse, you may still change the zoom level programmatically by changing the value in the region property.

Import Statement

Availability

A Boolean value that determines whether the user may scroll around the map.

Declaration

Swift

var scrollEnabled: Bool

Objective-C

@property(nonatomic,getter=isScrollEnabled)BOOLscrollEnabled

Discussion

This property controls only user interactions with the map. If you set the value of this property to NOfalse, you may still change the map location programmatically by changing the value in the region property.

Import Statement

Availability

Declaration

Swift

var pitchEnabled: Bool

Objective-C

@property(nonatomic,getter=isPitchEnabled)BOOLpitchEnabled

Discussion

When this property is set to YEStrue and a valid camera is associated with the map, the camera’s pitch angle is used to tilt the plane of the map. When this property is set to NOfalse, the camera’s pitch angle is ignored and the map is always displayed as if the user is looking straight down onto it.

Availability

Declaration

Swift

var rotateEnabled: Bool

Objective-C

@property(nonatomic,getter=isRotateEnabled)BOOLrotateEnabled

Discussion

When this property is set to YEStrue and a valid camera is associated with the map, the camera’s heading angle is used to rotate the plane of the map around its center point. When this property is set to NOfalse, the camera’s heading angle is ignored and the map is always oriented so that true north is situated at the top of the map view.

Declaration

Discussion

A map view sends messages to its delegate regarding the loading of map data and changes in the portion of the map being displayed. The delegate also manages the annotation views used to highlight points of interest on the map.

Declaration

Discussion

The region encompasses both the latitude and longitude point on which the map is centered and the span of coordinates to display. The span values provide an implicit zoom value for the map. The larger the displayed area, the lower the amount of zoom. Similarly, the smaller the displayed area, the greater the amount of zoom.

Changing only the center coordinate of the region can still cause the span to change implicitly. The span might change because the distances represented by a span change at different latitudes and longitudes and the map view may need to adjust the span to account for the new location. If you want to change the center coordinate without changing the zoom level, use the centerCoordinate instead.

Changing the value of this property updates the map view immediately. When setting this property, the map may adjust the new region value so that it fits the visible area of the map precisely. This is normal and is done to ensure that the value in this property always reflects the visible portion of the map. However, it does mean that if you get the value of this property right after setting it, the returned value may not match the value you set. (You can use the regionThatFits: method to determine the region that will actually be set by the map.)

If you want to animate the change in region, use the setRegion:animated: method instead.

Parameters

Specify YEStrue if you want the map view to animate the transition to the new region or NOfalse if you want the map to center on the specified region immediately.

Discussion

Changing just the center coordinate of the region can still cause the span values to change implicitly. The span values might change because that the distances represented by a span change at different latitudes and longitudes and the map view may need to adjust the span to account for the new location. If you want to change the center coordinate without changing the zoom level, use the setCenterCoordinate:animated: instead.

When setting a new region, the map may adjust the value in the region parameter so that it fits the visible area of the map precisely. This adjustment is normal and is done to ensure that the value in the region property always reflects the visible portion of the map. However, it does mean that if you get the value of that property right after calling this method, the returned value may not match the value you set. (You can use the regionThatFits: method to determine the region that will actually be set by the map.)

Declaration

Discussion

Changing the value in this property centers the map on the new coordinate without changing the current zoom level. It also updates the values in the region property to reflect the new center coordinate and the new span values needed to maintain the current zoom level.

Changing the value of this property updates the map view immediately. If you want to animate the change, use the setCenterCoordinate:animated: method instead.

Parameters

Specify YEStrue if you want the map view to scroll to the new location or NOfalse if you want the map to display the new location immediately.

Discussion

Changing the center coordinate centers the map on the new coordinate without changing the current zoom level. It also updates the value in the region property to reflect the new center coordinate and the new span values needed to maintain the current zoom level.

Declaration

Discussion

A camera object defines a point above the map’s surface from which to view the map. Applying a camera to a map has the effect of giving the map a 3D-like appearance. You can use a camera to rotate the map so that it is oriented to match the user’s heading or to apply a pitch angle to tilt the plane of the map.

Assigning a new camera to this property updates the map immediately and without animating the change. If you want to animate changes in camera position, use the setCamera:animated: method instead.

You must not set this property to nil. To restore the map to a flat appearance, apply a camera with a pitch angle of 0, which yields a camera looking straight down onto the map surface.

Import Statement

Availability

A Boolean indicating whether the map displays extruded building information.

Declaration

Swift

var showsBuildings: Bool

Objective-C

@property(nonatomic)BOOLshowsBuildings

Discussion

When this property is set to YEStrue and the camera has a pitch angle greater than zero, the map extrudes buildings so that they extend above the map plane, creating a 3D effect. The mapType property must be set to MKMapTypeStandard for extruded buildings to be displayed. The default value of this property is YEStrue.

Import Statement

Availability

A Boolean value indicating whether the map should try to display the user’s location.

Declaration

Swift

var showsUserLocation: Bool

Objective-C

@property(nonatomic)BOOLshowsUserLocation

Discussion

This property does not indicate whether the user’s position is actually visible on the map, only whether the map view should try to display it. Setting this property to YEStrue causes the map view to use the Core Location framework to find the current location and try to display it on the map. As long as this property is YEStrue, the map view continues to track the user’s location and update it periodically. The default value of this property is NOfalse.

Showing the user’s location does not guarantee that the location is visible on the map. The user might have scrolled the map to a different point, causing the current location to be offscreen. To determine whether the user’s current location is currently displayed on the map, use the userLocationVisible property.

Declaration

Discussion

This property tells you whether the icon used to represent the user’s current location is visible in the map view. When determining whether the current location is visible, this property factors in the horizontal accuracy of the location data. Specifically, if the rectangle represented by the user’s current location plus or minus minus the horizontal accuracy of that location intersects the map’s visible rectangle, this property contains the value YEStrue. If that location rectangle does not intersect the map’s visible rectangle, this property contains the value NOfalse.

If the user’s location cannot be determined, this property contains the value NOfalse.

Declaration

Parameters

annotation

The annotation object to remove. This object must conform to the MKAnnotation protocol.

Discussion

If the annotation is currently associated with an annotation view, and that view has a reuse identifier, this method removes the annotation view and queues it internally for later reuse. You can retrieve queued annotation views (and associate them with new annotations) using the dequeueReusableAnnotationViewWithIdentifier: method.

Removing an annotation object disassociates it from the map view entirely, preventing it from being displayed on the map. Thus, you would typically call this method only when you want to hide or delete a given annotation.

Declaration

Parameters

annotations

The array of annotations to remove. Objects in the array must conform to the MKAnnotation protocol.

Discussion

If any annotation object in the array has an associated annotation view, and if that view has a reuse identifier, this method removes the annotation view and queues it internally for later reuse. You can retrieve queued annotation views (and associate them with new annotations) using the dequeueReusableAnnotationViewWithIdentifier: method.

Removing annotation objects disassociates them from the map view entirely, preventing them from being displayed on the map. Thus, you would typically call this method only when you want to hide or delete the specified annotations.

Declaration

Parameters

annotation

The annotation object whose view you want.

Return Value

The annotation view or nil if the view has not yet been created. This method may also return nil if the annotation is not in the visible map region and therefore does not have an associated annotation view.

Declaration

Parameters

mapRect

The portion of the map that you want to search for annotations.

Return Value

The set of annotation objects located in mapRect.

Discussion

This method offers a fast way to retrieve the annotation objects in a particular portion of the map. This method is much faster than doing a linear search of the objects in the annotations property yourself.

Special Considerations

Prior to iOS 7 this method incorrectly did not return instances of MKUserLocation.

Parameters

A string identifying the annotation view to be reused. This string is the same one you specify when initializing the annotation view using the initWithAnnotation:reuseIdentifier: method.

Return Value

An annotation view with the specified identifier, or nil if no such object exists in the reuse queue.

Discussion

For performance reasons, you should generally reuse MKAnnotationView objects in your map views. As annotation views move offscreen, the map view moves them to an internally managed reuse queue. As new annotations move onscreen, and your code is prompted to provide a corresponding annotation view, you should always attempt to dequeue an existing view before creating a new one. Dequeueing saves time and memory during performance-critical operations such as scrolling.

Declaration

Discussion

This property contains the union of all overlays at the different levels of the map. The objects in this array must adopt the MKOverlay protocol. If no overlays are associated with the map view, the value of this property is an empty array.

The order of the objects in this array does not necessary reflect their visual order on the map.

Declaration

Parameters

The map level whose overlays you want. For a list of possible values for this parameter, see MKOverlayLevel.

Return Value

An array of objects conforming to the MKOverlay protocol that display in the specified map level. If there are no overlays at the specified level, this method returns an empty array.

Discussion

You can use this method to get all of the overlays assigned to a specific map level, which might be a subset of the complete set of overlay objects. For overlapping overlay objects, the order of objects in the array represents their visual order when displayed on the map, with objects in the beginning of the array located behind those at later indexes.

Declaration

Parameters

The overlay object to add. This object must conform to the MKOverlay protocol.

level

The map level at which to place the overlay. For a list of possible values for this parameter, see MKOverlayLevel.

Discussion

Positioning an overlay at a specific level places that overlay’s visual representation in front of or behind other map content such as map labels and point-of-interest icons.

This method adds the specified overlay to the end of the list of overlay objects at the given level. Adding an overlay also causes the map view to begin monitoring the area they represent. As soon as the bounding rectangle of the overlay intersects the visible portion of the map, the map view calls your delegate’s mapView:rendererForOverlay: method to get the renderer object to use when drawing the overlay.

Declaration

Parameters

The array of overlay objects to add. Each object in the array must conform to the MKOverlay protocol.

level

The map level at which to place the overlays. For a list of possible values for this parameter, see MKOverlayLevel.

Discussion

Positioning an overlay at a specific level places that overlay’s visual representation in front of or behind other map content such as map labels and point-of-interest icons.

This method adds the specified overlays to the end of the list of overlay objects at the given level. Adding the overlays also causes the map view to begin monitoring the area they represent. As soon as the bounding rectangle of an overlay intersects the visible portion of the map, the map view calls your delegate’s mapView:rendererForOverlay: method to get the renderer object to use when drawing that overlay.

Declaration

Parameters

overlay

The overlay object to add. This object must conform to the MKOverlay protocol.

Discussion

The specified object is added to the group of overlay objects in the MKOverlayLevelAboveLabels level. Adding an overlay causes the map view to begin monitoring the area represented by that overlay. As soon as the bounding rectangle of an overlay intersects the visible portion of the map, the map view adds a corresponding overlay view to the map. The overlay view is provided by the mapView:viewForOverlay: method of the map view’s delegate object.

Declaration

Parameters

overlays

An array of objects, each of which must conform to the MKOverlay protocol.

Discussion

The specified objects are added to the group of overlay objects in the MKOverlayLevelAboveLabels level. Adding an overlay causes the map view to begin monitoring the area represented by that overlay. As soon as the bounding rectangle of the overlay intersects the visible portion of the map, the map view tries to draw the overlay. As soon as the bounding rectangle of an overlay intersects the visible portion of the map, the map view adds a corresponding overlay view to the map. The overlay view is provided by the mapView:viewForOverlay: method of the map view’s delegate object.

Declaration

Parameters

overlay

The overlay object to insert.

sibling

An existing object in the overlays array. This object must exist in the array and must not be nil.

Discussion

This method inserts the overlay into the MKOverlayLevelAboveLabels level and positions it relative to the specified sibling. When displayed, this leads to the overlay’s contents being displayed above that of its sibling. If sibling is not in the same map level, this method appends the overlay to the end of the list of overlays at the indicated level.

Declaration

Parameters

overlay

The overlay object to insert.

sibling

An existing object in the overlays array. This object must exist in the array and must not be nil.

Discussion

This method inserts the overlay into the MKOverlayLevelAboveLabels level and positions it relative to the specified sibling. When displayed, this leads to the overlay’s contents being displayed beneath that of its sibling. If sibling is not in the same map level, this method appends the overlay to the end of the list of overlays at the indicated level.

Declaration

Parameters

overlay1

The first overlay object.

overlay2

The second overlay object.

Discussion

If the overlays are in the same map level, they exchange positions within that level’s array of overlay objects. If they are in different map levels, the two objects also swap levels. Swapping the position of the overlays affects their visibility in the map view.

Declaration

Parameters

overlay

The overlay object to remove.

Discussion

This method removes the overlay regardless of the level that it is in. Removing an overlay also removes its corresponding renderer, if one is in use. If the specified overlay is not currently associated with the map view, this method does nothing.

Declaration

Parameters

overlays

An array of objects, each of which conforms to the MKOverlay protocol.

Discussion

This method removes the specified overlays regardless of which level each one is in. Removing an overlay also removes its corresponding renderer, if one is in use. If a given overlay object is not associated with the map view, it is ignored.

Parameters

coordinate

The map coordinate for which you want to find the corresponding point.

view

The view in whose coordinate system you want to locate the specified map coordinate. If this parameter is nil, the returned point is specified in the window’s coordinate system. If view is not nil, it must belong to the same window as the map view.

Return Value

The point (in the appropriate view or window coordinate system) corresponding to the specified latitude and longitude value.

Declaration

Parameters

region

The map region for which you want to find the corresponding view rectangle.

view

The view in whose coordinate system you want to locate the specified map region. If this parameter is nil, the returned rectangle is specified in the window’s coordinate system. If view is not nil, it must belong to the same window as the map view.

Parameters

Return Value

A region that is still centered on the same point of the map but whose span values are adjusted to fit in the map view’s frame.

Discussion

You can use this method to normalize the region values before displaying them in the map. This method returns a new region that both contains the specified region and fits neatly inside the map view’s frame.

Parameters

Return Value

A map rectangle that is still centered on the same point of the map but whose width and height are adjusted to fit in the map view’s frame.

Discussion

You can use this method to normalize map rectangle values before displaying the corresponding area. This method returns a new map rectangle that both contains the specified rectangle and fits neatly inside the map view’s frame.