Class

MKMapView

An embeddable map interface, similar to the one provided by the Maps application.

Declaration

iOS, Mac Catalyst, tvOS
@interface MKMapView : UIView
macOS
@interface MKMapView : NSView

Overview

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. When you initialize a map view, you specify the initial region for that map to display 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 should be visible and is also how you set the zoom level. For example, specifying a large span results in the user seeing in a wide geographical area at a low zoom level, whereas specifying a small span results in a more narrow geographical area and 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.

In macOS 10.14 and later, you can apply a light or dark appearance to your maps by modifying the appearance property of your map view (or one of its ancestor views). Even if you specify a custom appearance, users can use the Maps app to force all maps to adopt a light appearance. Use the map view's effectiveAppearance property to determine the actual appearance of your map. For information about how to set view appearances, see Choosing a Specific Appearance for Your macOS App.

Annotating the Map

The MKMapView class supports the ability to annotate the map with custom information. Because a map may have 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 marker icon to denote specific points of interest on a map. (The Map Kit framework offers the MKMarkerAnnotationView and MKPinAnnotationView classes 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 macOS 10.9 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.

Topics

Customizing the Map View Behavior

delegate

The receiver’s delegate.

MKMapViewDelegate

Optional methods that you use to receive map-related update messages.

Accessing Map Properties

mapType

The type of data displayed by the map view.

MKMapType

The type of map to display.

zoomEnabled

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

scrollEnabled

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

pitchEnabled

A Boolean value indicating whether the map camera’s pitch information is used.

rotateEnabled

A Boolean value indicating whether the map camera’s heading information is used.

Manipulating the Visible Portion of the Map

region

The area currently displayed by the map view.

- setRegion:animated:

Changes the currently visible region and optionally animates the change.

centerCoordinate

The map coordinate at the center of the map view.

- setCenterCoordinate:animated:

Changes the center coordinate of the map and optionally animates the change.

- showAnnotations:animated:

Sets the visible region so that the map displays the specified annotations.

visibleMapRect

The area currently displayed by the map view.

- setVisibleMapRect:animated:

Changes the currently visible portion of the map and optionally animates the change.

- setVisibleMapRect:edgePadding:animated:

Changes the currently visible portion of the map, allowing you to specify additional space around the edges.

Constraining the Map View

Optimizing Map Views with Filtering and Camera Constraints

Display a map that is relevant to the user by filtering points of interest and search results, and constraining the visible region.

- setCameraBoundary:animated:

Set the camera boundary for the map view, specifying whether to use animation.

cameraBoundary

The boundary of the area within which this map view's center must remain.

- setCameraZoomRange:animated:

Set the camera zoom range for the map view, specifying whether to use animation.

cameraZoomRange

The zoom range applied to this map view.

MKMapCameraBoundary

A boundary of an area within which the map's center must remain.

MKMapCameraZoomRange

A range that determines the minimum and maximum distance of the camera to the center of the map.

Configuring the Map’s Appearance

- setCamera:animated:

Changes the camera used for determining the map’s viewing parameters and optionally animates the change.

camera

The camera used for determining the appearance of the map.

pointOfInterestFilter

The filter used to determine the points of interest shown on the map.

showsBuildings

A Boolean indicating whether the map displays extruded building information.

showsCompass

A Boolean indicating whether the map displays a compass control.

showsZoomControls

A Boolean indicating whether the map displays zoom controls.

showsScale

A Boolean indicating whether the map shows scale information.

showsTraffic

A Boolean value indicating whether the map displays traffic information.

showsPointsOfInterest

A Boolean indicating whether the map displays point-of-interest information.

Deprecated

Displaying the User’s Location

Converting a User's Location to a Descriptive Placemark

Transform the user’s location displayed on a map into an informative description.

showsUserLocation

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

userLocationVisible

A Boolean value indicating whether the device’s current location is visible in the map view.

userLocation

The annotation object representing the user’s current location.

userTrackingMode

The mode used to track the user location.

- setUserTrackingMode:animated:

Sets the mode used to track the user location with optional animation.

MKUserTrackingMode

The mode used to track the user location on the map.

Annotating the Map

annotations

The complete list of annotations associated with the receiver.

- addAnnotation:

Adds the specified annotation to the map view.

- addAnnotations:

Adds an array of annotation objects to the map view.

- removeAnnotation:

Removes the specified annotation object from the map view.

- removeAnnotations:

Removes an array of annotation objects from the map view.

- annotationsInMapRect:

Returns the annotation objects located in the specified map rectangle.

Managing Annotation Selections

annotationVisibleRect

The visible rectangle where annotation views are currently being displayed.

selectedAnnotations

The annotations that are currently selected.

- selectAnnotation:animated:

Selects the specified annotation and displays a callout view for it.

- deselectAnnotation:animated:

Deselects the specified annotation and hides its callout view.

Creating Annotation Views

- registerClass:forAnnotationViewWithReuseIdentifier:

Registers an annotation view class that the map can create automatically.

- dequeueReusableAnnotationViewWithIdentifier:forAnnotation:

Returns a reusable annotation view using the specified identifier.

- dequeueReusableAnnotationViewWithIdentifier:

Returns a reusable annotation view located by its identifier.

- viewForAnnotation:

Returns the annotation view associated with the specified annotation object, if any.

MKMapViewDefaultAnnotationViewReuseIdentifier

The default reuse identifier for your map's annotation views.

MKMapViewDefaultClusterAnnotationViewReuseIdentifier

The default reuse identifier for the annotation view representing a cluster of annotations.

Accessing Overlays

overlays

The overlay objects currently associated with the map view.

- overlaysInLevel:

The overlay objects in the specified level of the map.

- rendererForOverlay:

Returns the renderer object used to draw the contents of the specified overlay object.

- viewForOverlay:

Returns the view associated with the overlay object if any.

Deprecated
MKOverlayLevel

Constants indicating the position of overlays relative to other content.

Adding and Inserting Overlays

- addOverlay:level:

Adds the overlay object to the map at the specified level.

- addOverlays:level:

Adds an array of overlay objects to the map at the specified level.

- addOverlay:

Adds a single overlay object to the map.

- addOverlays:

Adds an array of overlay objects to the map.

- insertOverlay:atIndex:level:

Inserts an overlay object into the level at the specified index.

- insertOverlay:atIndex:

Inserts an overlay object into the list associated with the map.

- insertOverlay:aboveOverlay:

Inserts one overlay object on top of another.

- insertOverlay:belowOverlay:

Inserts one overlay object below another.

- exchangeOverlay:withOverlay:

Exchanges the positions of the two overlay objects.

- exchangeOverlayAtIndex:withOverlayAtIndex:

Exchanges the position of two overlay objects.

Removing Overlays

- removeOverlay:

Removes a single overlay object from the map.

- removeOverlays:

Removes one or more overlay objects from the map.

Converting Map Coordinates

- convertCoordinate:toPointToView:

Converts a map coordinate to a point in the specified view.

- convertPoint:toCoordinateFromView:

Converts a point in the specified view’s coordinate system to a map coordinate.

- convertRegion:toRectToView:

Converts a map region to a rectangle in the specified view.

- convertRect:toRegionFromView:

Converts a rectangle in the specified view’s coordinate system to a map region.

Adjusting Map Regions and Rectangles

- regionThatFits:

Adjusts the aspect ratio of the specified region to ensure that it fits in the map view’s frame.

- mapRectThatFits:

Adjusts the aspect ratio of the specified map rectangle to ensure that it fits in the map view’s frame.

- mapRectThatFits:edgePadding:

Adjusts the aspect ratio of the specified map rectangle, incorporating the specified inset values.

Relationships

Inherits From

Conforms To

See Also

Map Fundamentals

MKMapItem

A point of interest on the map.