MapKit Framework Reference

Map Kit Framework Reference

Contents

Introduction 10About the Map Kit Framework 11

Classes 12

MKAnnotationView Class Reference 13Overview 13

Tasks 15

Properties 17

Instance Methods 24

Constants 27

Notifications 28

MKCircle Class Reference 30Overview 30

Tasks 31

Properties 31

Class Methods 33

MKCircleRenderer Class Reference 35Overview 35

Tasks 35

Properties 36

Instance Methods 36

MKCircleView Class Reference 37Overview 37

Tasks 38

Properties 38

Instance Methods 38

MKDirections Class Reference 40Overview 40

Tasks 40

2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.

2

Properties 41

Instance Methods 41

Constants 44

MKDirectionsRequest Class Reference 46Overview 46

Tasks 47

Properties 48

Class Methods 50

Instance Methods 50

Constants 52

MKDirectionsResponse Class Reference 54Overview 54

Tasks 54

Properties 55

MKETAResponse Class Reference 57Overview 57

Tasks 57

Properties 58

MKGeodesicPolyline Class Reference 60Overview 60

Tasks 60

Class Methods 61

MKLocalSearch Class Reference 63Overview 63

Tasks 63

Properties 64

Instance Methods 64

Constants 66

MKLocalSearchRequest Class Reference 67Overview 67

Tasks 67

Properties 68

MKLocalSearchResponse Class Reference 69


3

Contents

Overview 69

Tasks 69

Properties 70

MKMapCamera Class Reference 71Overview 71

Tasks 71

Properties 72

Class Methods 74

MKMapItem Class Reference 76Overview 76

Tasks 77

Properties 78

Class Methods 80

Instance Methods 82

Constants 83

MKMapSnapshot Class Reference 86Overview 86

Tasks 86

Properties 87

Instance Methods 87

MKMapSnapshotOptions Class Reference 88Overview 88

Tasks 88

Properties 89

MKMapSnapshotter Class Reference 93Overview 93

Tasks 93

Properties 94

Instance Methods 94

Constants 97

MKMapView Class Reference 98Overview 98

Tasks 101

Properties 105


4

Contents

Instance Methods 115

Constants 139

MKMultiPoint Class Reference 142Overview 142

Tasks 142

Properties 143


MKOverlayPathRenderer Class Reference 145Overview 145

Tasks 145

Properties 147


MKOverlayPathView Class Reference 154Overview 154

Tasks 155

Properties 156


MKOverlayRenderer Class Reference 165Overview 165

Tasks 166

Properties 167


MKOverlayView Class Reference 175Overview 175

Tasks 176

Properties 177


MKPinAnnotationView Class Reference 186Overview 186

Tasks 187

Properties 187

Constants 188

MKPlacemark Class Reference 190


5

Contents

Overview 190

Tasks 191

Properties 191


MKPointAnnotation Class Reference 193Overview 193

Tasks 194

Properties 194

MKPolygon Class Reference 195Overview 195

Tasks 196

Properties 196

Class Methods 197

MKPolygonRenderer Class Reference 200Overview 200

Tasks 200

Properties 201


MKPolygonView Class Reference 202Overview 202

Tasks 203

Properties 203


MKPolyline Class Reference 205Overview 205

Tasks 206

Class Methods 206

MKPolylineRenderer Class Reference 208Overview 208

Tasks 208

Properties 209


MKPolylineView Class Reference 210


6

Contents

Overview 210

Tasks 211

Properties 211


MKReverseGeocoder Class Reference 213Overview 213

Tasks 214

Properties 215


MKRoute Class Reference 219Overview 219

Tasks 219

Properties 220

MKRouteStep Class Reference 224Overview 224

Tasks 224

Properties 225

MKShape Class Reference 228Overview 228

Tasks 229

Properties 229

MKTileOverlay Class Reference 231Overview 231

Tasks 232

Properties 232


Constants 238

MKTileOverlayRenderer Class Reference 239Overview 239

Tasks 239


MKUserLocation Class Reference 241Overview 241


7

Contents

Tasks 242

Properties 242

MKUserTrackingBarButtonItem Class Reference 245Overview 245

Tasks 245

Properties 246


NSValue MapKit Additions Reference 247Overview 247

Tasks 247

Class Methods 248


Protocols 250

MKAnnotation Protocol Reference 251Overview 251

Tasks 252

Properties 252


MKMapViewDelegate Protocol Reference 255Overview 255

Tasks 256


MKOverlay Protocol Reference 271Overview 271

Tasks 272

Properties 272


MKReverseGeocoderDelegate Protocol Reference 275Overview 275

Tasks 276


Functions 278


8

Contents

Map Kit Functions Reference 279Overview 279

Functions by Task 279

Functions 282

Data Types 307

Map Kit Data Types Reference 308Overview 308

Data Types 308

Constants 313

Map Kit Constants Reference 314Overview 314

Constants 314

Document Revision History 317


9

Contents

Framework /System/Library/Frameworks/MapKit.framework

Header file directories /System/Library/Frameworks/MapKit.framework/Headers

Companion guide Location and Maps Programming Guide

Declared in MKAnnotation.h

MKAnnotationView.h

MKCircle.h

MKCircleRenderer.h

MKCircleView.h

MKDirections.h

MKDirectionsRequest.h

MKDirectionsResponse.h

MKDirectionsTypes.h

MKGeodesicPolyline.h

MKGeometry.h

MKLocalSearch.h

MKLocalSearchRequest.h

MKLocalSearchResponse.h

MKMapCamera.h

MKMapItem.h

MKMapSnapshot.h

MKMapSnapshotOptions.h

MKMapSnapshotter.h

MKMapView.h

MKMultiPoint.h

MKOverlay.h

MKOverlayPathRenderer.h

MKOverlayPathView.h

MKOverlayRenderer.h

MKOverlayView.h

MKPinAnnotationView.h


10

MKPlacemark.h

MKPointAnnotation.h

MKPolygon.h

MKPolygonRenderer.h

MKPolygonView.h

MKPolyline.h

MKPolylineRenderer.h

MKPolylineView.h

MKReverseGeocoder.h

MKShape.h

MKTileOverlay.h

MKTileOverlayRenderer.h

MKTypes.h

MKUserLocation.h

MKUserTrackingBarButtonItem.h

About the Map Kit FrameworkThe Map Kit 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.

Important: In iOS 5.1 and earlier, the Map Kit framework uses the Google Mobile Maps (GMM) service toprovide 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.

About the Map Kit Framework


11


12

Classes

Inherits from UIView : UIResponder : NSObject

Conforms to NSCoding (UIView)

UIAppearance (UIView)

UIAppearanceContainer (UIView)

UIDynamicItem (UIView)

NSObject (NSObject)


Availability Available in iOS 3.0 and later.

Declared in MKAnnotationView.h


Related sample code KMLViewer

MapCallouts

MapSearch

PhotosByLocation

Regions

OverviewThe 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 annotations 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.


13

MKAnnotationView Class Reference




The most efficient way to provide the content for an annotation view is to set its image (page 21) property.

The annotation view sizes itself automatically to the image you specify and draws that image for its contents.

Because it is a view, however, you could also override the drawRect: method and draw your views content

manually. If you choose to override drawRect: directly and you do not specify a custom image in the image

property, be aware that the width and height of the annotation views frame are set to 0 by default. Before

your custom content can be drawn, you must set the width and height to nonzero values by modifying the

views frame property. In general, if your content consists entirely of static images, it is more efficient to set

the image property and change it as needed than to draw the images yourself.

Annotation views remain anchored to the map at the point specified by their associated annotation object.

Although they scroll with the map contents, annotation views reside in a separate display layer and are not

scaled when the size of the visible map region changes.

Annotation views support the concept of a selection state, which determines whether the view is unselected,

selected, or selected and displaying a standard callout view. The user toggles between the selection states

through interactions with the annotation view. In the unselected state, the annotation view is displayed but

not highlighted. In the selected state, the annotation is highlighted but the callout is not displayed. And finally,

the annotation can be displayed both with a highlight and a callout. The callout view displays additional

information such as a title string and controls for viewing more information. The title information is provided

by the annotation object but your annotation view is responsible for providing any custom controls. For more

information, see the subclassing notes.

Reusing Annotation ViewsAnnotation views are designed to be reused as the user (or your application) changes the visible map region.

The reuse of annotation views provides significant performance improvements during scrolling by avoiding

the creation of new view objects during this time critical operation. For this reason, annotation views should

not be tightly coupled to the contents of their associated annotation. Instead, it should be possible to use the

properties of an annotation view (or setter methods) to configure the view for a new annotation object.

Whenever you initialize a new annotation view, you should always specify a reuse identifier for that view. As

annotation views are no longer needed, the map view may put them into a reuse queue. As new annotations

are added to the map view, the delegate object can then dequeue and reconfigure an existing view (rather

than create a new one) using the dequeueReusableAnnotationViewWithIdentifier: (page 122) method of

MKMapView.

MKAnnotationView Class ReferenceOverview


14

Subclassing NotesYou can use the MKAnnotationView class as is or subclass it to provide custom behavior as needed. The

image (page 21) property of the class lets you set the appearance of the annotation view without subclassing

directly. You might also create custom subclasses as a convenience and use them to put the annotation view

in a known state. For example, the MKPinAnnotationView subclass initializes the contents of the annotation

view to a pin image.

There are no special requirements for subclassing MKAnnotationView. However, the following list includes

some reasons you might want to subclass and some of the methods you would override to implement the

desired behavior:

To put the annotation view into a consistent state, provide a custom initialization method. Your custom

initialization method would then call initWithAnnotation:reuseIdentifier: (page 24) to initialize the

superclass.

To provide custom callout views, override the leftCalloutAccessoryViewmethod and use it to return

the views.

If you support draggable annotation views in iOS 4.0 and later, your subclass is responsible for changing the

value in the dragState (page 19) property to appropriate values at key transition points in the drag operation.

For more information, see the description of that property.

Tasks

Initializing and Preparing the View

initWithAnnotation:reuseIdentifier: (page 24)

Initializes and returns a new annotation view.

prepareForReuse (page 25)

Called when the view is removed from the reuse queue.

Getting and Setting Attributes

enabled (page 21) property

A Boolean value indicating whether the annotation is enabled.

image (page 21) property

The image to be displayed by the annotation view.

MKAnnotationView Class ReferenceTasks


15

highlighted (page 21) property

A Boolean value indicating whether the annotation view is highlighted.

annotation (page 17) property

The annotation object currently associated with the view.

centerOffset (page 18) property

The offset (in pixels) at which to display the view.

calloutOffset (page 17) property

The offset (in pixels) at which to place the callout bubble.

reuseIdentifier (page 22) property

The string that identifies that this annotation view is reusable. (read-only)

Managing the Selection State

setSelected:animated: (page 27)

Sets the selection state of the annotation view.

selected (page 24) property

A Boolean value indicating whether the annotation view is currently selected.

Managing Callout Views

canShowCallout (page 18) property

A Boolean value indicating whether the annotation view is able to display extra information in a callout

bubble.

leftCalloutAccessoryView (page ?) property

The view to display on the left side of the standard callout bubble.

rightCalloutAccessoryView (page ?) property

The view to display on the right side of the standard callout bubble.

Supporting Drag Operations

draggable (page 19) property

A Boolean indicating whether the annotation view is draggable.

MKAnnotationView Class ReferenceTasks


16

setDragState:animated: (page 26)

Sets the current drag state for the annotation view.

dragState (page 19) property

The current drag state of the annotation view.

Properties

annotation

The annotation object currently associated with the view.

@property (nonatomic, retain) id annotation

DiscussionYou should not change the value of this property directly. This property contains a non-nil value only while

the annotation view is visible on the map. If the view is queued and waiting to be reused, the value is nil

AvailabilityAvailable in iOS 3.0 and later.

Related Sample CodeMapCalloutsRegions

Declared inMKAnnotationView.h

calloutOffset

The offset (in pixels) at which to place the callout bubble.

@property (nonatomic) CGPoint calloutOffset

DiscussionThis property determines the additional distance by which to move the callout bubble. When this property is

set to (0, 0), the anchor point of the callout bubble is placed on the top-center point of the annotation views

frame. Specifying positive offset values moves the callout bubble down and to the right, while specifying

negative values moves it up and to the left.


MKAnnotationView Class ReferenceProperties


17


canShowCallout

A Boolean value indicating whether the annotation view is able to display extra information in a callout bubble.

@property (nonatomic) BOOL canShowCallout

DiscussionIf the value of this property is YES, a standard callout bubble is shown when the user taps a selected annotation

view. The callout uses the title and subtitle text from the associated annotation object. If there is no title text,

though, the annotation view is treated as if its enabled property is set to NO. The callout also displays any

custom callout views stored in the leftCalloutAccessoryView and rightCalloutAccessoryView

properties.

If the value of this property is NO, the value of the title and subtitle strings are ignored and the annotation view

remains enabled by default. You can still disable the view explicitly using the enabled property.


See Also @property leftCalloutAccessoryView (page 22) @property rightCalloutAccessoryView (page 23)

Related Sample CodeKMLViewerMapCalloutsMapSearchPhotosByLocation


centerOffset

The offset (in pixels) at which to display the view.



18

@property (nonatomic) CGPoint centerOffset

DiscussionBy default, the center point of an annotation view is placed at the coordinate point of the associated annotation.

You can use this property to reposition the annotation view as needed. This x and y offset values are measured

in pixels. Positive offset values move the annotation view down and to the right, while negative values move

it up and to the left.


Related Sample CodeMapCallouts


draggable

A Boolean indicating whether the annotation view is draggable.

@property (nonatomic, getter=isDraggable) BOOL draggable

DiscussionSetting this property to YES makes an annotation draggable by the user. If YES, the associated annotation

object must also implement the setCoordinate: (page 254) method. The default value of this property is NO.

Setting this property to YES, lets the map view know that the annotation is always draggable. In other words,

you cannot conditionalize drag operations by attempting to stop an operation that has already been initiated;

doing so can lead to undefined behavior. Once begun, the drag operation should always continue to completion.



dragState

The current drag state of the annotation view.



19

@property (nonatomic) MKAnnotationViewDragState dragState

DiscussionApplications targeting iOS 4.1 and earlier can use this property to support drag operations in custom annotation

views. If your application runs in iOS 4.2 or later, you should override the setDragState:animated: (page 26)

method and use it to manage the drag state instead.

To support drag operations, you must override the implementation of this property and update the drag state

at the following times:

When the drag state changes to MKAnnotationViewDragStateStarting (page 28), you should set the

state to MKAnnotationViewDragStateDragging (page 28). If you perform an animation to indicate the

beginning of a drag, you should perform that animation before changing the state. Changing the state

to the new value lets the map know that your animations are done.

When the state changes to either MKAnnotationViewDragStateCanceling (page 28) or

MKAnnotationViewDragStateEnding (page 28), set the state to MKAnnotationViewDragStateNone (page

28). If you perform an animation at the end of a drag, you should perform that animation before changing

the state.

Changing the state to theMKAnnotationViewDragStateDraggingorMKAnnotationViewDragStateNone

value is the way to signal to the map view that you are done with any animations you wanted to perform. For

example, when a drag operation begins for a pin annotation, the MKPinAnnotationView class executes an

animation to lift the pin off the map. Similarly, when the pin is dropped, the class performs a drop animation.

Even if you do not perform any animations, you should still change the value of this property to reflect the

correct state.

You must not try to abort a new drag operation by changing the state from

MKAnnotationViewDragStateStarting toMKAnnotationViewDragStateNone. If you do not want your

annotation view to be draggable, set the draggable (page 19) property to NO.


See Also @property draggable (page 19)




20

enabled

A Boolean value indicating whether the annotation is enabled.

@property (nonatomic, getter=isEnabled) BOOL enabled

DiscussionThe default value of this property is YES. If the value of this property is NO, the annotation view ignores touch

events and cannot be selected. Subclasses may also display the annotation contents differently depending on

the value of this property.



highlighted

A Boolean value indicating whether the annotation view is highlighted.

@property (nonatomic, getter=isHighlighted) BOOL highlighted

DiscussionYou should not set the value of this property directly. The map view sets it in response to touch events entering

or exiting the annotation views bounds.



image

The image to be displayed by the annotation view.

@property (nonatomic, retain) UIImage *image

DiscussionAssigning a new image to this property also changes the size of the views frame so that it matches the width

and height of the new image. The position of the views frame does not change.



21




leftCalloutAccessoryView

The view to display on the left side of the standard callout bubble.

@property (retain, nonatomic) UIView *leftCalloutAccessoryView

DiscussionThe default value of this property is nil. The left callout view is typically used to display information about

the annotation or to link to custom information provided by your application.

If the view you specify is also a descendant of the UIControl class, you can use the map views delegate to

receive notifications when your control is tapped. If it does not descend from UIControl, your view is

responsible for handling any touch events within its bounds.


See Also @property canShowCallout (page 18)

Related Sample CodeMapCalloutsPhotosByLocationRegions


reuseIdentifier

The string that identifies that this annotation view is reusable. (read-only)



22

@property (nonatomic, readonly) NSString *reuseIdentifier

DiscussionYou specify the reuse identifier when you create the view. You use this type later to retrieve an annotation

view that was created previously but which is currently unused because its annotation is not on screen.

If you define distinctly different types of annotations (with distinctly different annotation views to go with

them), you can differentiate between the annotation types by specifying different reuse identifiers for each

one.




rightCalloutAccessoryView

The view to display on the right side of the standard callout bubble.

@property (retain, nonatomic) UIView *rightCalloutAccessoryView

DiscussionThis property is set to nil by default. The right callout view is typically used to link to more detailed information

about the annotation. A common view to specify for this property is UIButton object whose type is set to

UIButtonTypeDetailDisclosure.

If the view you specify is also a descendant of the UIControl class, you can use the map views delegate to

receive notifications when your control is tapped. If it does not descend from UIControl, your view is

responsible for handling any touch events within its bounds.


See Also @property canShowCallout (page 18)

Related Sample CodeMapCalloutsPhotosByLocation



23


selected

A Boolean value indicating whether the annotation view is currently selected.

@property (nonatomic, getter=isSelected) BOOL selected

DiscussionYou should not set the value of this property directly. If the property contains YES, the annotation view is

displaying a callout bubble.



Instance Methods

initWithAnnotation:reuseIdentifier:

Initializes and returns a new annotation view.

- (id)initWithAnnotation:(id )annotation reuseIdentifier:(NSString*)reuseIdentifier

Parametersannotation

The annotation object to associate with the new view.

reuseIdentifier

If you plan to reuse the annotation view for similar types of annotations, pass a string to identify it.

Although you can pass nil if you do not intend to reuse the view, reusing annotation views is generally

recommended.

Return ValueThe initialized annotation view or nil if there was a problem initializing the object.

MKAnnotationView Class ReferenceInstance Methods


24

DiscussionThe reuse identifier provides a way for you to improve performance by recycling annotation views as they are

scrolled on and off of the map. As views are no longer needed, they are moved to a reuse queue by the map

view. When a new annotation becomes visible, your application can request a view for that annotation by

passing the appropriate reuse identifier string to the dequeueReusableAnnotationViewWithIdentifier: (page

122) method of MKMapView.


Related Sample CodeKMLViewerMapCalloutsMapSearchPhotosByLocationRegions


prepareForReuse

Called when the view is removed from the reuse queue.

- (void)prepareForReuse

DiscussionThe default implementation of this method does nothing. You can override it in your custom annotation views

and use it to put the view in a known state before it is returned to your map view delegate.


See AlsodequeueReusableAnnotationViewWithIdentifier: (page 122) (MKMapView)

Related Sample CodePhotosByLocation




25

setDragState:animated:

Sets the current drag state for the annotation view.

- (void)setDragState:(MKAnnotationViewDragState)newDragState animated:(BOOL)animated

ParametersnewDragState

The new drag state for the annotation view.

animated

If YES, the change to the new drag state should be animated; otherwise, it should be made without

animations.

DiscussionApplications targeting iOS 4.2 and later can override this method and use it to implement drag support for

custom annotation views. As the system detects user actions that would indicate a drag, it calls this method

to update the drag state. In response to these changes, your custom implementation of this method should

do the following:

When the drag state changes to MKAnnotationViewDragStateStarting (page 28), set the state to

MKAnnotationViewDragStateDragging (page 28). If you perform an animation to indicate the beginning

of a drag, and the animated parameter is YES, perform that animation before changing the state.

When the state changes to either MKAnnotationViewDragStateCanceling (page 28) or

MKAnnotationViewDragStateEnding (page 28), set the state to MKAnnotationViewDragStateNone (page

28). If you perform an animation at the end of a drag, and the animated parameter is YES, you should

perform that animation before changing the state.

The default implementation of this method sets the value of the dragState (page 19) property to the value

in the newDragState parameter only. Therefore, direct subclasses can simply call the inherited version of this

method to change the drag state; otherwise, just change the value in the draggable property directly.

Changing the state to MKAnnotationViewDragStateDragging or MKAnnotationViewDragStateNone

is the way to signal to the map view that you are done with any animations you wanted to perform. For example,

when a drag operation begins for a pin annotation, the MKPinAnnotationView class executes an animation

to lift the pin off the map. Similarly, when the pin is dropped, the class performs a drop animation. Even if you

do not perform any animations, you should call the inherited version of this method to update the

dragState (page 19) property.

You must not try to abort a new drag operation by changing the state from

MKAnnotationViewDragStateStarting toMKAnnotationViewDragStateNone. If you do not want your

annotation view to be draggable, set the draggable (page 19) property to NO.



26



setSelected:animated:

Sets the selection state of the annotation view.

- (void)setSelected:(BOOL)selected animated:(BOOL)animated

Parametersselected

Contains the value YES if the view should display itself as selected.

animated

Set to YES if the change in selection state is animated.

DiscussionYou should not call this method directly. An MKMapView object calls this method in response to user interactions

with the annotation.


See AlsoselectAnnotation:animated: (page 133) (MKMapView)


Constants

MKAnnotationViewDragState

These constants indicate the current drag state of an annotation view.

typedef enum MKAnnotationViewDragState {MKAnnotationViewDragStateNone = 0,MKAnnotationViewDragStateStarting,MKAnnotationViewDragStateDragging,

MKAnnotationView Class ReferenceConstants


27

MKAnnotationViewDragStateCanceling,MKAnnotationViewDragStateEnding

} MKAnnotationViewDragState;

ConstantsMKAnnotationViewDragStateNone

The view is not involved in a drag operation. The annotation view is responsible for returning itself to

this state when a drag ends or is canceled.

Available in iOS 4.0 and later.

Declared in MKAnnotationView.h.

MKAnnotationViewDragStateStarting

An action occurred that indicated the view should begin dragging. The map view automatically moves

annotation views to this state in response to appropriate user actions.



MKAnnotationViewDragStateDragging

The view is in the middle of a drag operation and is tracking progress.



MKAnnotationViewDragStateCanceling

An action occurred that indicated the view should cancel the drag operation. You can put an annotation

view into this state to abort the operation.



MKAnnotationViewDragStateEnding

An action occurred that indicated the view was dropped by the user. The map view automatically moves

annotation views to this state in response to appropriate user actions.



Notifications

MKAnnotationCalloutInfoDidChangeNotification

Notifies observers that the title or subtitle information of an annotation object changed. (#Deprecated. Use KVO

notifications instead.)

MKAnnotationView Class ReferenceNotifications


28

This notification supports legacy applications and is no longer necessary. MapKit tracks changes to the title

and subtitle of an annotation using KVO notifications.



MKAnnotationView Class ReferenceNotifications


29

Inherits from MKShape : NSObject

Conforms to MKOverlay

MKAnnotation (MKShape)

NSObject (NSObject)



Declared in MKCircle.h


Related sample code Regions

OverviewThe 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.


30

MKCircle Class Reference




Tasks

Creating a Circle Overlay

+ circleWithCenterCoordinate:radius: (page 33)

Creates and returns an MKCircle object using the specified coordinate and radius.

+ circleWithMapRect: (page 33)

Creates and returns an MKCircle object where the circular area is derived from the specified rectangle.

Accessing the Overlays Attributes

coordinate (page 32) property

The center point of the circular area, specified as a latitude and longitude. (read-only)

radius (page 32) property

The radius of the circular area, measured in meters. (read-only)

boundingMapRect (page 31) property

The bounding rectangle of the circular area. (read-only)

Properties

boundingMapRect

The bounding rectangle of the circular area. (read-only)

MKCircle Class ReferenceTasks


31

@property (nonatomic, readonly) MKMapRect boundingMapRect

DiscussionAs latitude values move away from the equator and toward the poles, the physical distance between map

points gets smaller. This means that more map points are needed to represent the same distance. As a result,

the bounding rectangle of a circle overlay gets larger as the center point of that circle moves away from the

equator and toward the poles.


Declared inMKCircle.h

coordinate

The center point of the circular area, specified as a latitude and longitude. (read-only)

@property (nonatomic, readonly) CLLocationCoordinate2D coordinate


Related Sample CodeRegions


radius

The radius of the circular area, measured in meters. (read-only)

@property (nonatomic, readonly) CLLocationDistance radius



MKCircle Class ReferenceProperties


32

Class Methods

circleWithCenterCoordinate:radius:

Creates and returns an MKCircle object using the specified coordinate and radius.

+ (MKCircle *)circleWithCenterCoordinate:(CLLocationCoordinate2D)coordradius:(CLLocationDistance)radius

Parameterscoord

The center point of the circle, specified as a latitude and longitude value.

radius

The radius of the circle, measured in meters from the center point.

Return ValueA circle overlay object.


Related Sample CodeRegions


circleWithMapRect:

Creates and returns an MKCircle object where the circular area is derived from the specified rectangle.

+ (MKCircle *)circleWithMapRect:(MKMapRect)mapRect

ParametersmapRect

The map rectangle used to determine the circular area. The center point of the rectangle is used as the

center point of the circle. If the rectangle is not a square, the longest side of the rectangle is used to

define the radius of the resulting circle.

Return ValueA circle overlay object.

MKCircle Class ReferenceClass Methods


33



MKCircle Class ReferenceClass Methods


34

Inherits from MKOverlayPathRenderer : MKOverlayRenderer : NSObject

Conforms to NSObject (NSObject)



Declared in MKCircleRenderer.h

OverviewThe 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.

You create an instance of this class in your map view delegates mapView:rendererForOverlay: (page 265)

method.

Tasks

Initializing the Renderer Object

initWithCircle: (page 36)

Initializes and returns a new overlay view using the specified circle overlay object.

Accessing the Overlay Object

circle (page 36) property

The circle overlay object that contains the information used to draw the overlay. (read-only)


35

MKCircleRenderer Class Reference

Properties

circle

The circle overlay object that contains the information used to draw the overlay. (read-only)

@property(nonatomic, readonly) MKCircle *circle


Declared inMKCircleRenderer.h

Instance Methods

initWithCircle:

Initializes and returns a new overlay view using the specified circle overlay object.

- (id)initWithCircle:(MKCircle *)circle

Parameterscircle

The circle overlay containing the information about the circular area to be drawn. The renderer maintains

a strong reference to the object you provide. This parameter must not be nil.

Return ValueAn initialized circle renderer object.


Declared inMKCircleRenderer.h

MKCircleRenderer Class ReferenceProperties


36

Inherits from MKOverlayPathView : MKOverlayView : UIView : UIResponder : NSObject

Conforms to NSCoding (UIView)

UIAppearance (UIView)

UIAppearanceContainer (UIView)

UIDynamicItem (UIView)

NSObject (NSObject)



Declared in MKCircleView.h


Related sample code Regions

OverviewThe 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.




Use of this class is discouraged in iOS 7 and later. Use the MKCircleRenderer class instead.


37

MKCircleView Class Reference

Tasks

Initializing the Overlay View

initWithCircle: (page 38)

Initializes and returns a new overlay view using the specified circle overlay object. (Deprecated. Use the

MKCircleRenderer class instead.)

Accessing the Overlay

circle (page 38) property

The circle overlay object that contains the information used to draw the overlay. (read-only) (Deprecated.

Use the MKCircleRenderer class instead.)

Properties

circle

The circle overlay object that contains the information used to draw the overlay. (read-only) (Deprecated in iOS

7.0. Use the MKCircleRenderer class instead.)

@property (nonatomic, readonly) MKCircle *circle


Deprecated in iOS 7.0.

Declared inMKCircleView.h

Instance Methods

initWithCircle:

Initializes and returns a new overlay view using the specified circle overlay object. (Deprecated in iOS 7.0. Use the

MKCircleRenderer class instead.)

MKCircleView Class ReferenceTasks


38

- (id)initWithCircle:(MKCircle *)circle

Parameterscircle

The circle overlay containing the information about the circular area to be drawn.

Return ValueA new circle overlay view.


Deprecated in iOS 7.0.

Declared inMKCircleView.h

MKCircleView Class ReferenceInstance Methods


39

Inherits from NSObject




Declared in MKDirections.h


OverviewAn 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.

Each directions object handles a single request for directions, although you can cancel and restart that request

as needed. You can create multiple instances of this class and process different route requests at the same

time, but you should make requests only when you plan to present the corresponding route information to

the user. Apps may receive a MKErrorLoadingThrottled (page 316) error if too many requests have been made

from the current device in too short a time period.

Tasks

Initializing a Directions Object

initWithRequest: (page 43)

Initializes and returns a directions object using the specified request.


40

MKDirections Class Reference

Getting the Directions

calculateDirectionsWithCompletionHandler: (page 41)

Begins calculating the requested route information asynchronously.

calculateETAWithCompletionHandler: (page 42)

Begins calculating the requested travel-time information asynchronously.

cancel (page 43)

Cancels a pending request.

calculating (page 41) property

A Boolean value indicating whether a request is currently in process. (read-only)

Properties

calculating

A Boolean value indicating whether a request is currently in process. (read-only)

@property (nonatomic, readonly, getter=isCalculating) BOOL calculating


Declared inMKDirections.h

Instance Methods

calculateDirectionsWithCompletionHandler:

Begins calculating the requested route information asynchronously.

-(void)calculateDirectionsWithCompletionHandler:(MKDirectionsHandler)completionHandler

ParameterscompletionHandler

The block to execute when the directions are ready or when an error occurs. This parameter must not

be nil.

MKDirections Class ReferenceProperties


41

DiscussionThis method initiates the request for directions and calls your completion handler block with the results. Your

completion handler is executed on your apps main thread. The implementation of your handler should check

for errors and then incorporate the response data as appropriate.

If you call this method while a previous request is in process, this method calls your completion handler with

an error. You can determine if a request is in process by checking the value of the calculating property.

You can also cancel a request as needed.


See Also @property calculating (page 41) cancel (page 43)


calculateETAWithCompletionHandler:

Begins calculating the requested travel-time information asynchronously.

- (void)calculateETAWithCompletionHandler:(MKETAHandler)completionHandler


The block to execute when the travel-time estimate is ready or when an error occurs. This parameter

must not be nil.

DiscussionThis method initiates a request for a travel-time estimate and calls your completion handler block with the

results. Travel-time estimates take much less time to generate than directions, so use this method in situations

where you want a time estimate only. Your completion handler is executed on your apps main thread. The

implementation of your handler should check for errors and then incorporate the response data as appropriate.

If you call this method while a previous request is in process, this method calls your completion handler with

an error. You can determine if a request is in process by checking the value of the calculating property.

You can also cancel a request as needed.


MKDirections Class ReferenceInstance Methods


42


cancel

Cancels a pending request.

- (void)cancel

DiscussionAfter canceling a request, you can call the calculateDirectionsWithCompletionHandler: (page 41) method

again (if you want) to restart the request process.



initWithRequest:

Initializes and returns a directions object using the specified request.

- (instancetype)initWithRequest:(MKDirectionsRequest *)request

Parametersrequest

The request object containing the start and end points of the route. This parameter must not be nil.

Return ValueAn initialized directions object.

DiscussionAfter initializing your directions object, you must call the calculateDirectionsWithCompletionHandler: (page

41) or calculateETAWithCompletionHandler: (page 42) method to perform the request.



MKDirections Class ReferenceInstance Methods


43

Constants

MKDirectionsHandler

The block to use for processing the requested route information.

typedef void (^MKDirectionsHandler)(MKDirectionsResponse *response, NSError *error);

DiscussionThis block takes two parameters:

The response parameter contains the route information for the request. If an error occurred or no route

could be determined, this parameter is nil.

The error parameter contains information about any errors that occurred. If no errors occurred, this

parameter is nil.

The implementation of your block should check for a value in the error parameter and, if that parameter is

nil, incorporate the route information provided in the response parameter.



MKETAHandler

The block to use for processing travel-time information.

typedef void (^MKETAHandler)(MKETAResponse *response, NSError *error);


The response parameter contains the travel time response. If an error occurred or no travel time could

be determined, this parameter is nil.

The error parameter contains information about any errors that occurred. If no errors occurred, this

parameter is nil.

MKDirections Class ReferenceConstants


44

The implementation of your block should check for a value in the error parameter and, if that parameter is

nil, incorporate the travel-time information provided in the response parameter.



MKDirections Class ReferenceConstants


45





Declared in MKDirectionsRequest.h


OverviewThe 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.

For apps that provide directions, upon receiving a URL in your app delegates

application:openURL:sourceApplication:annotation: method, use the

isDirectionsRequestURL: (page 50) method of this class to determine if the URL is related to routing

directions. If it is, create an instance of this class using the provided URL and extract the map items associated

with the start and end points. You can then use those points to begin your route planning.


46

MKDirectionsRequest Class Reference

Note: To provide routing directions, apps must include special keys in their Info.plist file and

be able to handle URLs sent to it by the Maps app. These keys indicate a special URL type that your

app must be prepared to handle. For information about how to implement this support, see Location

and Maps Programming Guide .

You can use this class to request directions for modes of transportation that your app does not natively handle.

For example, an app that provides subway directions might request walking directions to and from relevant

subway stations. To request directions, create a new instance of this class and configure it with the new start

and end points you need. Then create a MKDirections object and use the methods of that class to initiate

the request and process the results.

Tasks

Creating a Directions Request Object

+ isDirectionsRequestURL: (page 50)

Returns a Boolean indicating whether the specified URL contains a directions request.

initWithContentsOfURL: (page 51)

Initializes and returns a directions request object using the specified URL.

Accessing the Start and End Points

source (page 52)

Returns the starting point for routing directions.

setSource: (page 52)

Sets the starting point for routing directions.

destination (page 50)

Returns the end point for routing directions

setDestination: (page 51)

Sets the end point for routing directions

MKDirectionsRequest Class ReferenceTasks


47

Specifying Transportation Options

transportType (page 49) property

The type of conveyance to which the directions should apply.

requestsAlternateRoutes (page 49) property

A Boolean indicating whether your app wants multiple routes when they are available.

departureDate (page 48) property

The departure date for the trip.

arrivalDate (page 48) property

The arrival date for the trip.

Properties

arrivalDate

The arrival date for the trip.

@property (nonatomic, retain) NSDate *arrivalDate;

DiscussionSpecifying an arrival date provides the server with extra information that it can use to optimize the returned

routes. For example, for a trip that takes place during commute hours, the server might consider alternatives

to routes that are typically congested at that time.

The use of this property is optional.


Declared inMKDirectionsRequest.h

departureDate

The departure date for the trip.

@property (nonatomic, retain) NSDate *departureDate;

MKDirectionsRequest Class ReferenceProperties


48

DiscussionSpecifying a departure date provides the server with extra information that it can use to optimize the returned

routes. For example, for a trip that takes place during commute hours, the server might consider alternatives

to routes that are typically congested at that time.

The use of this property is optional.



requestsAlternateRoutes

A Boolean indicating whether your app wants multiple routes when they are available.

@property (nonatomic) BOOL requestsAlternateRoutes;

DiscussionWhen this property is set to NO, the server returns a single route between the start and end points. When this

property is YES, the server may return additional routes for the user to follow. The server returns additional

routes only if they are available and represent a reasonable path that the user might take.

The default value of this property is NO.



transportType

The type of conveyance to which the directions should apply.

@property (nonatomic) MKDirectionsTransportType transportType;

DiscussionYou can use this property to specify whether you want directions suited to a particular type of transportation.

For example, you can use this to specify that you want walking directions or driving directions.

The default value of this property is MKDirectionsTransportTypeAny (page 53).

MKDirectionsRequest Class ReferenceProperties


49



Class Methods

isDirectionsRequestURL:

Returns a Boolean indicating whether the specified URL contains a directions request.

+ (BOOL)isDirectionsRequestURL:(NSURL *)url

Parametersurl

The URL provided to your app.

Return ValueYES if the URL contains a directions request that your app should display to the user or NO if it does not.



Instance Methods

destination

Returns the end point for routing directions

- (MKMapItem *)destination

Return ValueThe end point for routing directions.


MKDirectionsRequest Class ReferenceClass Methods


50


initWithContentsOfURL:

Initializes and returns a directions request object using the specified URL.

- (id)initWithContentsOfURL:(NSURL *)url

Parametersurl

The URL provided to your app.

Return ValueAn initialized directions request object.

DiscussionYou should use the isDirectionsRequestURL: (page 50) method to verify that the specified URL is of the

correct format before calling this method to initialize the object.



setDestination:

Sets the end point for routing directions

- (void)setDestination:(MKMapItem *)destination

Parametersdestination

The map item that represents the end point for routing directions.



MKDirectionsRequest Class ReferenceInstance Methods


51

setSource:

Sets the starting point for routing directions.

- (void)setSource:(MKMapItem *)source

Parameterssource

The map item that represents the starting point for routing directions.



source

Returns the starting point for routing directions.

- (MKMapItem *)source

Return ValueThe starting point for routing directions.



Constants

MKDirectionsTransportType

Constants that specify the type of conveyance to be used.

typedef enum {MKDirectionsTransportTypeAutomobile = 1

MKDirectionsTransportTypeAny = NSUIntegerMax} MKDirectionsTransportType;

ConstantsMKDirectionsTransportTypeAutomobile

Directions suitable for use while driving.


Declared in MKDirectionsTypes.h.

MKDirectionsTransportTypeWalking

Directions suitable for a pedestrian.



MKDirectionsTransportTypeAny

Directions suitable for any transportation option.



MKDirectionsRequest Class ReferenceConstants


53




Declared in MKDirectionsResponse.h

OverviewThe 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 calculateDirectionsWithCompletionHandler: (page 41) method of an MKDirections

object. You receive an instance of this class as the result.

Tasks

Getting the End Points

source (page 55) property

The start point of the route. (read-only)

destination (page 55) property

The end point of the route. (read-only)

Getting the Route Information

routes (page 55) property

An array of route objects representing the directions between the start and end points. (read-only)


54

MKDirectionsResponse Class Reference

Properties

destination


@property (nonatomic, readonly) MKMapItem *destination

DiscussionThe item in this property may contain additional details that were not included in the original item used to

create the MKDirectionsRequest object.


Declared inMKDirectionsResponse.h

routes

An array of route objects representing the directions between the start and end points. (read-only)

@property (nonatomic, readonly) NSArray *routes

DiscussionThe array contains one or more MKRoute objects, each of which represents a possible set of directions for the

user to follow. If you did not request alternate routes in the original directions request, this array contains at

most one object.

Each route object contains geometry information that you can use to display that route on your apps map

view. Routes may also contain additional information that is relevant to that particular route, such as the

expected travel time and any trip advisory notices.



source


MKDirectionsResponse Class ReferenceProperties


55

@property (nonatomic, readonly) MKMapItem *source





MKDirectionsResponse Class ReferenceProperties


56





Declared in MKDirectionsResponse.h


OverviewThe 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 calculateETAWithCompletionHandler: (page 42) method of an MKDirections object.

You receive an instance of this class as the result.

Tasks

Getting the End Points

source (page 59) property


destination (page 58) property



57

MKETAResponse Class Reference

Getting the Travel Time

expectedTravelTime (page 58) property

The expected travel time in seconds. (read-only)

Properties

destination


@property (nonatomic, readonly) MKMapItem *destination





expectedTravelTime

The expected travel time in seconds. (read-only)

@property (nonatomic, readonly) NSTimeInterval expectedTravelTime

DiscussionThis expected travel time reflects the time it takes to traverse the route under ideal conditions. The actual

amount of time may vary based on traffic, weather, and other travel conditions.



MKETAResponse Class ReferenceProperties


58

source


@property (nonatomic, readonly) MKMapItem *source

DiscussionThis item in this property may contain additional details that were not included in the original item used to




MKETAResponse Class ReferenceProperties


59

Inherits from MKPolyline : MKMultiPoint : MKShape : NSObject

Conforms to MKOverlay (MKPolyline)

MKAnnotation (MKShape)

NSObject (NSObject)



Declared in MKGeodesicPolyline.h

OverviewThe 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.

Tasks

Creating a Geodesic Polyline Overlay

+ polylineWithPoints:count: (page 61)

Creates and returns an geodesic polyline using the specified map points.

+ polylineWithCoordinates:count: (page 61)

Creates and returns an geodesic polyline using the specified coordinates.


60

MKGeodesicPolyline Class Reference

Class Methods

polylineWithCoordinates:count:

Creates and returns an geodesic polyline using the specified coordinates.

+ (instancetype)polylineWithCoordinates:(CLLocationCoordinate2D *)coordscount:(NSUInteger)count

Parameterscoords

A pointer to the array of coordinates that define the path.

count

The number of items in the coords array.

Return ValueA new geodesic polyline object.


Declared inMKGeodesicPolyline.h

polylineWithPoints:count:

Creates and returns an geodesic polyline using the specified map points.

+ (instancetype)polylineWithPoints:(MKMapPoint *)points count:(NSUInteger)count

Parameterspoints

A pointer to the array of map points that define the path.

count

The number of items in the points array.

Return ValueA new geodesic polyline object.


MKGeodesicPolyline Class ReferenceClass Methods


61

Declared inMKGeodesicPolyline.h

MKGeodesicPolyline Class ReferenceClass Methods


62





Declared in MKLocalSearch.h


OverviewAn 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.

You use this class to perform programmatic searches of map-based information. For example, you can use this

class to search for addresses or points-of-interest in much the same way the user might search for those items

in the Maps app.

Tasks

Initializing a Search Request

initWithRequest: (page 65)

Initializes and returns a search object configured with the specified parameters.


63

MKLocalSearch Class Reference

Performing the Search

startWithCompletionHandler: (page 65)

Starts the search and delivers the results to the specified completion handler.

searching (page 64) property

A Boolean indicating whether the search is currently in progress. (read-only)

cancel (page 64)

Cancels an in-progress search operation.

Properties

searching

A Boolean indicating whether the search is currently in progress. (read-only)

@property (nonatomic, readonly, getter=isSearching) BOOL searching;

DiscussionThe value of this property is set to YES when a search is initiated and remains in that state until the search

results (or an appropriate error) are delivered, at which time the property is set to NO.


Declared inMKLocalSearch.h

Instance Methods

cancel

Cancels an in-progress search operation.

- (void)cancel

DiscussionIf no search operation is in progress, this method does nothing.

MKLocalSearch Class ReferenceProperties


64



initWithRequest:

Initializes and returns a search object configured with the specified parameters.

- (id)initWithRequest:(MKLocalSearchRequest *)request

Parametersrequest

The search request information. This parameter must not be nil.

Return ValueAn initialized search object.

DiscussionThis method stores a copy of the object in the request parameter. So any changes you make to your request

object after calling this method are ignored.



startWithCompletionHandler:

Starts the search and delivers the results to the specified completion handler.

- (void)startWithCompletionHandler:(MKLocalSearchCompletionHandler)completionHandler


The completion handler block that processes the results. This parameter must not be nil.

DiscussionYou use this method to initiate a map-based search operation. The search runs until the results are delivered,

at which point the specified completion handler is called.

MKLocalSearch Class ReferenceInstance Methods


65

You should call this method only once to start the search operation. Calling this method while the search is

running does not stop the original search operation from finishing. However, for each subsequent call, the

search object executes your completion handler and passes an error object to it.

The provided completion handler is always executed on your apps main thread. The local search object keeps

a reference to the completion handler block until the results (or an error) are delivered, at which point it

relinquishes that reference.



Constants

MKLocalSearchCompletionHandler

A completion handler block for a search operation.

typedef void (^MKLocalSearchCompletionHandler)(MKLocalSearchResponse *response, NSError*error);


The response parameter contains the search results. If an error occurred, this parameter is set to nil

and an appropriate error object is provided in the error parameter.

The error parameter is nil if the search was successful. If an error occurred during the operation, this

parameter is set to an appropriate error object.

This block has no return value.



MKLocalSearch Class ReferenceConstants


66


Conforms to NSCopying

NSObject (NSObject)



Declared in MKLocalSearchRequest.h


OverviewAn MKLocalSearchRequest object is a utility object that you use to specify map-based search parameters.

After creating an instance of this object, you can assign a natural language string containing the address or

point-of-interest to search for. You can 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.

Tasks

Configuring the Search Parameters

naturalLanguageQuery (page 68) property

A string containing the desired search item.

region (page 68) property

A map region that provides a hint as to where to search.


67

MKLocalSearchRequest Class Reference

Properties

naturalLanguageQuery

A string containing the desired search item.

@property (nonatomic, copy) NSString *naturalLanguageQuery;

DiscussionYou specify this parameter as a string describing the map-based item you want to look for. The text is equivalent

to what the user would type in a search field in the Maps app. For example, the text might contain all or part

of an address or it might contain the name of a point of interest.

This property can not be nil.


Declared inMKLocalSearchRequest.h

region

A map region that provides a hint as to where to search.

@property (nonatomic, assign) MKCoordinateRegion region;

DiscussionYou can use this parameter to narrow the list of search results to those inside or close to the specified region.

Specifying a region does not guarantee that the results will all be inside the region. It is merely a hint to the

search engine.


Declared inMKLocalSearchRequest.h

MKLocalSearchRequest Class ReferenceProperties


68





Declared in MKLocalSearchResponse.h


OverviewAn MKLocalSearchResponse object contains the search results from a map-based search that was started

using an MKLocalSearch object.

Tasks

MethodGroup

mapItems (page 70) property

An array of map items representing the search results. (read-only)

boundingRegion (page 70) property

The map region that encloses the returned search results. (read-only)


69

MKLocalSearchResponse Class Reference

Properties

boundingRegion

The map region that encloses the returned search results. (read-only)

@property (nonatomic, readonly) MKCoordinateRegion boundingRegion;

DiscussionThe returned region is the smallest bounding box that encloses all of the map items. If there is only one search

result, the size of the region may be (0, 0).


Declared inMKLocalSearchResponse.h

mapItems

An array of map items representing the search results. (read-only)

@property (nonatomic, readonly) NSArray *mapItems;

DiscussionThis property contains an array of MKMapItem objects, each of which represents a returned search result. You

can use these objects to retrieve information about the search result, such as the name of the point of interest,

the address, the geographic location, and so on.


Declared inMKLocalSearchResponse.h

MKLocalSearchResponse Class ReferenceProperties


70


Conforms to NSCopying

NSSecureCoding

NSObject (NSObject)


Declared in MKMapView.h

OverviewAn 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 cameras viewing direction, the pitch of the camera relative to the map perpendicular, and

the cameras altitude above the map. These factors let you create a map view that is not just flat but offers a

more 3D-like experience.

After creating an instance of this class, configure it with the desired attributes and assign it to your map view.

When you assign a camera to your map view, the map centers the map using the value in your camera objects

centerCoordinate (page 72) property, updating the maps own region information in the process. The map

also takes the cameras the pitch and altitude into account when calculating the visible region, ensuring that

the region always encompasses the visible content on the map.

Tasks

Getting a Camera Object

+ camera (page 74)

Returns a new camera object for you to configure.


71

MKMapCamera Class Reference

+ cameraLookingAtCenterCoordinate:fromEyeCoordinate:eyeAltitude: (page 74)

Returns a new camera object using the specified viewing angle information.

Configuring the Viewing Angle

centerCoordinate (page 72) property

The map coordinate at the center of the map view.

heading (page 73) property

The heading of the camera (measured in degrees) relative to true north.

pitch (page 73) property

The viewing angle of the camera, measured in degrees.

altitude (page 72) property

The altitude above the ground, measured in meters.

Properties

altitude

The altitude above the ground, measured in meters.

@property (nonatomic) CLLocationDistance altitude;

DiscussionThe value you specify for this property must not be less than 0.

Changing this property may also change the maximum pitch that is allowed for the map. If the current pitch

value exceeds the new maximum, the pitch (page 73) property is clamped to the new maximum.


Declared inMKMapCamera.h

centerCoordinate

The map coordinate at the center of the map view.

MKMapCamera Class ReferenceProperties


72

@property (nonatomic) CLLocationCoordinate2D centerCoordinate;

DiscussionThis point represents the coordinate on which the map should be centered. When the camera pitch is 0, this

property also corresponds to the geographic position of the camera. Changing the pitch to a nonzero value

moves the camera but does not affect this property.



heading

The heading of the camera (measured in degrees) relative to true north.

@property (nonatomic) CLLocationDirection heading;

DiscussionThe value 0 means that the top edge of the map view corresponds to true north. The value 90 means the top

of the map is pointing due east. The value 180 means the top of the map points due south, and so on.



pitch

The viewing angle of the camera, measured in degrees.

@property (nonatomic) CGFloat pitch;

DiscussionA value of 0 results in a camera pointed straight down at the map. Angles greater than 0 result in a camera

that is pitched toward the horizon by the specified number of degrees. If the map type is

MKMapTypeSatellite (page 140) or MKMapTypeHybrid (page 140), the pitch value is clamped to 0.

The value in this property may be clamped to a maximum value to maintain map readability. There is no fixed

maximum value, though, because the actual maximum value is dependent on the current altitude of the

camera.

MKMapCamera Class ReferenceProperties


73



Class Methods

camera

Returns a new camera object for you to configure.

+ (instancetype)camera

Return ValueA new camera object.

DiscussionYou must change the values of the returned camera object before using it.



cameraLookingAtCenterCoordinate:fromEyeCoordinate:eyeAltitude:

Returns a new camera object using the specified viewing angle information.

+(instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate

fromEyeCoordinate:(CLLocationCoordinate2D)eyeCoordinateeyeAltitude:(CLLocationDistance)eyeAltitude

ParameterscenterCoordinate

The coordinate point on which the map should be centered.

MKMapCamera Class ReferenceClass Methods


74

eyeCoordinate

The coordinate point at which to place the camera. If the value for this parameter is equal to the value

in the centerCoordinate parameter, the map is displayed as if the camera is looking straight down. If

this point is offset from the centerCoordinate value, the map is displayed with an appropriate heading

and pitch angle.

eyeAltitude

The altitude (in meters) above the ground at which to place the camera.

Return ValueA new camera object initialized with the specified information.

DiscussionThis method calculates the required pitch and heading angles to accommodate the specified eye position and

altitude.



MKMapCamera Class ReferenceClass Methods


75





Declared in MKMapItem.h


Related sample code MapSearch

Using NSXMLParser to parse XML documents

OverviewThe 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 (page 80) method to get a map item that represents the users current location.

For privacy reasons, and because the users 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.

2013-09-18 | Copyright 2013 Apple Inc. All Righ

MapKit Framework Reference

Documents

Transcript of MapKit Framework Reference