Framework

MapKit

Display map or satellite imagery from the windows and views of your custom apps. Annotate your maps with points of interest, and determine placemark information for map coordinates.

Overview

The MapKit framework provides an interface for embedding maps directly into your own windows and views. This framework also provides support for annotating the map, adding overlays, and performing reverse-geocoding lookups to determine placemark information for a given map coordinate.

Symbols

Classes

MKAnnotationView

The MKAnnotationView class is responsible for presenting annotations visually in a map view. Annotation views are loosely coupled to a corresponding annotation object, which is an object that corresponds to the MKAnnotation protocol. When an annotation’s coordinate point is in the visible region, the map view asks its delegate to provide a corresponding annotation view. Annotation views may be recycled later and put into a reuse queue that is maintained by the map view.

MKCircle

The MKCircle class is a concrete overlay object representing a circular area on a map. This class manages the data that defines the area and is typically used in conjunction with an MKCircleView object, which handles the drawing of the circular area on a map.

MKCircleRenderer

The MKCircleRenderer class provides a visual representation for an MKCircle overlay object. This renderer draws by filling and stroking the circle represented by the overlay object. You can change the color and other drawing attributes of the circle by modifying the properties inherited from the parent class. You typically use this class as is and do not subclass it.

MKCircleView

The MKCircleView class provides the visual representation for an MKCircle annotation object. This view fills and strokes the circle represented by the annotation. You can change the color and other drawing attributes of the circle by modifying the properties inherited from the MKOverlayPathView class. This class is typically used as is and not subclassed.

MKDirections

An MKDirections object provides you with route-based directions data from Apple servers. You can use instances of this class to get travel-time information or driving or walking directions based on the data in an MKDirectionsRequest object that you provide. The directions object passes your request to the Apple servers and returns the requested information to a block that you provide.

MKDirectionsRequest

The MKDirectionsRequest class is used by apps that work with turn-based directions. When the Maps app sends a directions-related URL to your app, you use this class to decode the URL contents and determine the start and end points of a route. You then use that data to compute the actual route and display the results to the user. For apps that want to supplement their own routing directions, you can also use instances of this class to specify route information that you want from Apple.

MKDirectionsResponse

The MKDirectionsResponse class provides a container for route information returned by the Apple servers. You do not create instances of this class directly. Instead, you initiate a request for directions between two points by calling the calculate(completionHandler:) method of an MKDirections object. You receive an instance of this class as the result.

MKDistanceFormatter

The MKDistanceFormatter class implements a formatter object for geographic distances. You can apply a distance formatter in places where you need to specify distances and know that the values are formatted appropriately for the user’s locale and language. You can also parse existing format strings to retrieve the corresponding distance value.

MKETAResponse

The MKETAResponse class provides a container for travel-time information returned by the Apple servers. You do not create instances of this class directly. Instead, you initiate a request for the travel time between two points by calling the calculateETA(completionHandler:) method of an MKDirections object. You receive an instance of this class as the result.

MKGeodesicPolyline

The MKGeodesicPolyline class represents a line shape that traces the shortest path along the surface of the Earth. As with regular polyline overlays, you specify a geodesic polyline using a set of end-to-end points where the first and last points are not connected to each other. When displayed on a two-dimensional map view, the line segment between any two points may appear curved.

MKLocalSearch

An MKLocalSearch object initiates a map-based search operation and delivers the results back to your app asynchronously. Search objects are designed to perform one search operation only. To perform several different searches, you must create separate instances of this class and start them separately.

MKLocalSearchCompleter

An MKLocalSearchCompleter object takes a partial search string and generates a list of potential completions. You use a search completer object to retrieve auto-complete suggestions for your own map-based search controls. As the user types text, you feed the current text string into the search completer object, which delivers possible string completions that match locations or points of interest. You then use the fully-formed search completion objects to create an MKLocalSearch object and retrieve more detailed information about the geographic location.

MKLocalSearchCompletion

An MKLocalSearchCompletion object contains a fully formed search term derived from a partial term. You do not create instances of this class directly. Instead, you use an MKLocalSearchCompleter to start initiate a search using a partial search string and then return instances of this class to you. You can use the information in MKLocalSearchCompletion objects to update your user interface and to perform geographic searches using an MKLocalSearch object.

MKLocalSearchRequest

An MKLocalSearchRequest object is a utility object that you use to specify map-based search parameters. You can create an instance of this object and specify a natural language search string yourself, or you can use an MKLocalSearchCompleter object to obtain a more specific search term based on user input. You should also specify a specific map region to narrow the search results. You then use the configured object to initialize an MKLocalSearch object and perform your search.

MKLocalSearchResponse

An MKLocalSearchResponse object contains the search results from a map-based search that was started using an MKLocalSearch object.

MKMapCamera

An MKMapCamera object describes a virtual camera that you use to define the appearance of the map. A camera object creates a virtual viewpoint above the map surface and affects how the map renders its tiles and other content. You use a camera object to specify the location of the camera on the map, the compass heading that corresponds to the camera’s viewing direction, the pitch of the camera relative to the map perpendicular, and the camera’s altitude above the map. These factors let you create a map view that is not just flat but offers a more 3D-like experience.

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.

MKMapSnapshot

An MKMapSnapshot object contains an image generated by a snapshotter object. You do not create instances of this class directly. Instead, you use an MKMapSnapshotter object capture the map contents asynchronously. Upon completion, the snapshotter object generates an image based on the options you provide and delivers that image inside an instance of this class.

MKMapSnapshotOptions

The MKMapSnapshotOptions class specifies the options to use when capturing map-based imagery. After creating and configuring an instance of this class, you pass that instance to an MKMapSnapshotter object. The snapshotter uses the options you specify to determine the portion of the map to capture, the viewing angle to use for the camera, and the map appearance.

MKMapSnapshotter

An MKMapSnapshotter object captures map-based imagery asynchronously. Use instances of this class in situations where you want to capture the system-provided map content, including the map tiles and imagery. The snapshotter object always captures the best image possible, loading all of the available map tiles before capturing the image.

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.

MKMultiPoint

The MKMultiPoint class is an abstract superclass used to define shapes composed of multiple points. You should not create instances of this class directly. Instead, you should create instances of the MKPolyline or MKPolygon classes. However, you can use the methods and property of this class to access information about the specific points associated with the line or polygon.

MKOverlayPathRenderer

The MKOverlayPathRenderer class draws a map overlay whose shape is represented by a CGPath data type. The default drawing behavior of this class is to apply the object’s current fill attributes, fill the path, apply the current stroke attributes, and then stroke the path.

MKOverlayPathView

The MKOverlayPathView class represents a generic overlay that draws its contents using a CGPath data type. You can use this class to implement simple path-based overlay views or subclass it to define additional drawing behaviors. The default drawing behavior of this class is to apply the object’s current fill attributes, fill the path, apply the current stroke attributes, and then stroke the path.

MKOverlayRenderer

The MKOverlayRenderer class defines the basic behavior associated with all map-based overlays. An overlay renderer draws the visual representation of an overlay object—that is, an object that conforms to the MKOverlay protocol. This class defines the drawing infrastructure used by the map view. Subclasses are expected to override the draw(_:zoomScale:in:) method to draw the contents of the overlay.

MKOverlayView

The MKOverlayView class defines the basic behavior associated with all overlay views. An overlay view provides the visual representation of an overlay object—that is, an object that conforms to the MKOverlay protocol. This class defines the drawing infrastructure used by the map view but does not do any actual drawing. Subclasses are expected to override the drawMapRect:zoomScale:inContext: method in order to draw the contents of the overlay view.

MKPinAnnotationView

The MKPinAnnotationView class provides a concrete annotation view that displays a pin icon like the ones found in the Maps application. Using this class, you can configure the type of pin to drop and whether you want the pin to be animated into place.

MKPlacemark

A MKPlacemark object stores placemark data for a given latitude and longitude. Placemark data includes information such as the country, state, city, and street address associated with the specified coordinate. You can initialize a placemark using the init(placemark:) inherited method or the init(coordinate:addressDictionary:) method specifying a coordinate and address dictionary.

MKPointAnnotation

The MKPointAnnotation class defines a concrete annotation object located at a specified point. You can use this class, rather than define your own, in situations where all you want to do is associate a point on the map with a title.

MKPolygon

The MKPolygon class represents a shape consisting of one or more points that define a closed polygon. The points are connected end-to-end in the order they are provided. The first and last points are connected to each other to create the closed shape.

MKPolygonRenderer

The MKPolygonRenderer class provides the visual representation for an MKPolygon overlay object. This renderer fills and strokes the polygon represented by first filling the shape and then stroking its outline. You can change the color and other drawing attributes of the polygon by modifying the properties inherited from the parent class. You typically use this class as is and do not subclass it.

MKPolygonView

The MKPolygonView class provides the visual representation for an MKPolygon annotation object. This view fills and strokes the area represented by the annotation. You can change the color and other drawing attributes of the polygon by modifying the properties inherited from the MKOverlayPathView class. This class is typically used as is and not subclassed.

MKPolyline

The MKPolyline class represents a shape consisting of one or more points that define connecting line segments. The points are connected end-to-end in the order they are provided. The first and last points are not connected to each other.

MKPolylineRenderer

The MKPolylineRenderer class provides the visual representation for an MKPolyline overlay object. This renderer strokes the line only; it does not fill it. You can change the color and other drawing attributes of the polygon by modifying the properties inherited from the parent class. You typically use this class as is and do not subclass it.

MKPolylineView

The MKPolylineView class provides the visual representation for an MKPolyline annotation object. This view strokes the path represented by the annotation. (This class does not fill the area enclosed by the path.) You can change the color and other drawing attributes of the path by modifying the properties inherited from the MKOverlayPathView class. This class is typically used as is and not subclassed.

MKRoute

The MKRoute class defines a single route that the user can follow between a requested start and end point. The route object defines the geometry for the route and includes information you can display to the user in association with that route, such as the name of the route, its distance, and the expected travel time.

MKRouteStep

An MKRouteStep object represents one part of an overall route. Each step in a route corresponds to a single instruction that would need to be followed by the user. For example, a step might involve following a single road until a turn is required.

MKShape

The MKShape class is an abstract class that defines the basic properties for all shape-based annotation objects. This class must be subclassed and cannot be used as is. Subclasses are responsible for defining the geometry of the shape and providing an appropriate value for the coordinate property inherited from the MKAnnotation protocol.

MKTileOverlay

The MKTileOverlay class implements an overlay that is optimized for covering an area of the map using individual bitmap tiles. (In general, a map tile is a prerendered map image that covers a specific geographic area.) You can use tile overlay objects to represent your own tile-based content and to coordinate the display of that content in a map view. Your tiles can supplement the underlying map content or replace it completely. A tile overlay object coordinates the loading and management of the tiles while a corresponding MKTileOverlayRenderer object handles the actual drawing of the tiles on the map.

MKTileOverlayRenderer

An MKTileOverlayRenderer object handles the drawing of tiles managed by an MKTileOverlay object. You create instances of this class when tile overlays become visible on the map view. A renderer works closely with its associated tile overlay object to coordinate the loading and drawing of tiles at appropriate times.

MKUserLocation

The MKUserLocation class defines a specific type of annotation that identifies the user’s current location. You do not create instances of this class directly. Instead, you retrieve an existing MKUserLocation object from the userLocation property of the map view displayed in your app.

MKUserTrackingBarButtonItem

AnMKUserTrackingBarButtonItem object is a specialized bar button item that allows the user to toggle through the user tracking modes. For example, when the user taps the button, the map view toggles between tracking the user with and without heading. The button also reflects the current user tracking mode if set elsewhere. This bar button item is associated to a single map view.

Protocols

MKAnnotation

The MKAnnotation protocol is used to provide annotation-related information to a map view. To use this protocol, you adopt it in any custom objects that store or represent annotation data. Each object then serves as the source of information about a single map annotation and provides critical information, such as the annotation’s location on the map. Annotation objects do not provide the visual representation of the annotation but typically coordinate (in conjunction with the map view’s delegate) the creation of an appropriate MKAnnotationView object to handle the display.

MKLocalSearchCompleterDelegate

The MKLocalSearchCompleterDelegate protocol defines the methods for receiving search completion data from an MKLocalSearchCompleter object. You use this protocol when implementing an auto-complete solution that is tied to a map in your app. Upon receiving a partial search string, the MKLocalSearchCompleter object performs searches for valid completions matching that string and returns them to your delegate object as one or more MKLocalSearchCompletion objects.

MKMapViewDelegate

The MKMapViewDelegate protocol defines a set of optional methods that you can use to receive map-related update messages. Because many map operations require the MKMapView class to load data asynchronously, the map view calls these methods to notify your application when specific operations complete. The map view also uses these methods to request annotation and overlay views and to manage interactions with those views.

MKOverlay

The MKOverlay protocol defines a specific type of annotation that represents both a point and an area on a map. Overlay objects are essentially data objects that contain the geographic data needed to represent the map area. For example, overlays can take the form of common shapes such as rectangles and circles. They can also describe polygons and other complex shapes.

Reference

MapKit Functions

The functions of the MapKit framework provide convenient ways to package map-related data structures.

MapKit Data Types

This document describes the data types found in the Map Kit framework.

MapKit Constants

This document describes the constants found in the Map Kit framework

MapKit StructuresMapKit Enumerations

Extended Types

MKErrorName
NSUserActivity

An NSUserActivity object provides a lightweight way to capture the state of your app and put it to use later. You create user activity objects and use them to capture information about what the user was doing, such as viewing app content, editing a document, viewing a web page, or watching a video. When the system launches your app and an activity object is available, your app can use the information in that object to restore itself to an appropriate state. Spotlight also uses your user activity objects to improve search results for the user.

NSValue

An NSValue object is a simple container for a single C or Objective-C data item. It can hold any of the scalar types such as int, float, and char, as well as pointers, structures, and object id references. Use this class to work with such data types in collections (such as NSArray and NSSet), Key-value coding, and other APIs that require Objective-C objects. NSValue objects are always immutable.

See Also