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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
4
Contents
Instance Methods 115
Constants 139
MKMultiPoint Class Reference 142Overview 142
Tasks 142
Properties 143
Instance Methods 144
MKOverlayPathRenderer Class Reference 145Overview 145
Tasks 145
Properties 147
Instance Methods 150
MKOverlayPathView Class Reference 154Overview 154
Tasks 155
Properties 156
Instance Methods 161
MKOverlayRenderer Class Reference 165Overview 165
Tasks 166
Properties 167
Instance Methods 168
MKOverlayView Class Reference 175Overview 175
Tasks 176
Properties 177
Instance Methods 178
MKPinAnnotationView Class Reference 186Overview 186
Tasks 187
Properties 187
Constants 188
MKPlacemark Class Reference 190
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
5
Contents
Overview 190
Tasks 191
Properties 191
Instance Methods 192
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
Instance Methods 201
MKPolygonView Class Reference 202Overview 202
Tasks 203
Properties 203
Instance Methods 203
MKPolyline Class Reference 205Overview 205
Tasks 206
Class Methods 206
MKPolylineRenderer Class Reference 208Overview 208
Tasks 208
Properties 209
Instance Methods 209
MKPolylineView Class Reference 210
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
6
Contents
Overview 210
Tasks 211
Properties 211
Instance Methods 211
MKReverseGeocoder Class Reference 213Overview 213
Tasks 214
Properties 215
Instance Methods 217
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
Instance Methods 235
Constants 238
MKTileOverlayRenderer Class Reference 239Overview 239
Tasks 239
Instance Methods 240
MKUserLocation Class Reference 241Overview 241
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
7
Contents
Tasks 242
Properties 242
MKUserTrackingBarButtonItem Class Reference 245Overview 245
Tasks 245
Properties 246
Instance Methods 246
NSValue MapKit Additions Reference 247Overview 247
Tasks 247
Class Methods 248
Instance Methods 249
Protocols 250
MKAnnotation Protocol Reference 251Overview 251
Tasks 252
Properties 252
Instance Methods 254
MKMapViewDelegate Protocol Reference 255Overview 255
Tasks 256
Instance Methods 258
MKOverlay Protocol Reference 271Overview 271
Tasks 272
Properties 272
Instance Methods 273
MKReverseGeocoderDelegate Protocol Reference 275Overview 275
Tasks 276
Instance Methods 276
Functions 278
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
11
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
12
Classes
Inherits from UIView : UIResponder : NSObject
Conforms to NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
UIDynamicItem (UIView)
NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 3.0 and later.
Declared in MKAnnotationView.h
Companion guide Location and Maps Programming Guide
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.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
13
MKAnnotationView Class Reference
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.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 3.0 and later.
MKAnnotationView Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
17
Declared inMKAnnotationView.h
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.
AvailabilityAvailable in iOS 3.0 and later.
See Also @property leftCalloutAccessoryView (page 22) @property rightCalloutAccessoryView (page 23)
Related Sample CodeKMLViewerMapCalloutsMapSearchPhotosByLocation
Declared inMKAnnotationView.h
centerOffset
The offset (in pixels) at which to display the view.
MKAnnotationView Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 3.0 and later.
Related Sample CodeMapCallouts
Declared inMKAnnotationView.h
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.
AvailabilityAvailable in iOS 4.0 and later.
Declared inMKAnnotationView.h
dragState
The current drag state of the annotation view.
MKAnnotationView Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 4.0 and later.
See Also @property draggable (page 19)
Declared inMKAnnotationView.h
MKAnnotationView Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 3.0 and later.
Declared inMKAnnotationView.h
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.
AvailabilityAvailable in iOS 3.0 and later.
Declared inMKAnnotationView.h
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.
MKAnnotationView Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
21
AvailabilityAvailable in iOS 3.0 and later.
Related Sample CodeMapCallouts
Declared inMKAnnotationView.h
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.
AvailabilityAvailable in iOS 3.0 and later.
See Also @property canShowCallout (page 18)
Related Sample CodeMapCalloutsPhotosByLocationRegions
Declared inMKAnnotationView.h
reuseIdentifier
The string that identifies that this annotation view is reusable. (read-only)
MKAnnotationView Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 3.0 and later.
Related Sample CodeMapCallouts
Declared inMKAnnotationView.h
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.
AvailabilityAvailable in iOS 3.0 and later.
See Also @property canShowCallout (page 18)
Related Sample CodeMapCalloutsPhotosByLocation
MKAnnotationView Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
23
Declared inMKAnnotationView.h
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.
AvailabilityAvailable in iOS 3.0 and later.
Declared inMKAnnotationView.h
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 3.0 and later.
Related Sample CodeKMLViewerMapCalloutsMapSearchPhotosByLocationRegions
Declared inMKAnnotationView.h
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.
AvailabilityAvailable in iOS 3.0 and later.
See AlsodequeueReusableAnnotationViewWithIdentifier: (page 122) (MKMapView)
Related Sample CodePhotosByLocation
Declared inMKAnnotationView.h
MKAnnotationView Class ReferenceInstance Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
MKAnnotationView Class ReferenceInstance Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
26
AvailabilityAvailable in iOS 4.2 and later.
Declared inMKAnnotationView.h
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.
AvailabilityAvailable in iOS 3.0 and later.
See AlsoselectAnnotation:animated: (page 133) (MKMapView)
Declared inMKAnnotationView.h
Constants
MKAnnotationViewDragState
These constants indicate the current drag state of an annotation view.
typedef enum MKAnnotationViewDragState {MKAnnotationViewDragStateNone = 0,MKAnnotationViewDragStateStarting,MKAnnotationViewDragStateDragging,
MKAnnotationView Class ReferenceConstants
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
Available in iOS 4.0 and later.
Declared in MKAnnotationView.h.
MKAnnotationViewDragStateDragging
The view is in the middle of a drag operation and is tracking progress.
Available in iOS 4.0 and later.
Declared in MKAnnotationView.h.
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.
Available in iOS 4.0 and later.
Declared in MKAnnotationView.h.
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.
Available in iOS 4.0 and later.
Declared in MKAnnotationView.h.
Notifications
MKAnnotationCalloutInfoDidChangeNotification
Notifies observers that the title or subtitle information of an annotation object changed. (#Deprecated. Use KVO
notifications instead.)
MKAnnotationView Class ReferenceNotifications
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 3.0 and later.
Declared inMKAnnotationView.h
MKAnnotationView Class ReferenceNotifications
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
29
Inherits from MKShape : NSObject
Conforms to MKOverlay
MKAnnotation (MKShape)
NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 4.0 and later.
Declared in MKCircle.h
Companion guide Location and Maps Programming Guide
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.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
30
MKCircle Class Reference
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.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 4.0 and later.
Declared inMKCircle.h
coordinate
The center point of the circular area, specified as a latitude and longitude. (read-only)
@property (nonatomic, readonly) CLLocationCoordinate2D coordinate
AvailabilityAvailable in iOS 4.0 and later.
Related Sample CodeRegions
Declared inMKCircle.h
radius
The radius of the circular area, measured in meters. (read-only)
@property (nonatomic, readonly) CLLocationDistance radius
AvailabilityAvailable in iOS 4.0 and later.
Declared inMKCircle.h
MKCircle Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 4.0 and later.
Related Sample CodeRegions
Declared inMKCircle.h
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
33
AvailabilityAvailable in iOS 4.0 and later.
Declared inMKCircle.h
MKCircle Class ReferenceClass Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
34
Inherits from MKOverlayPathRenderer : MKOverlayRenderer : NSObject
Conforms to NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 7.0 and later.
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)
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
AvailabilityAvailable in iOS 7.0 and later.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKCircleRenderer.h
MKCircleRenderer Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
36
Inherits from MKOverlayPathView : MKOverlayView : UIView : UIResponder : NSObject
Conforms to NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
UIDynamicItem (UIView)
NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 4.0 and later.
Declared in MKCircleView.h
Companion guide Location and Maps Programming Guide
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.
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.
Use of this class is discouraged in iOS 7 and later. Use the MKCircleRenderer class instead.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
AvailabilityAvailable in iOS 4.0 and later.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 4.0 and later.
Deprecated in iOS 7.0.
Declared inMKCircleView.h
MKCircleView Class ReferenceInstance Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
39
Inherits from NSObject
Conforms to NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 7.0 and later.
Declared in MKDirections.h
Companion guide Location and Maps Programming Guide
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.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
AvailabilityAvailable in iOS 7.0 and later.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
See Also @property calculating (page 41) cancel (page 43)
Declared inMKDirections.h
calculateETAWithCompletionHandler:
Begins calculating the requested travel-time information asynchronously.
- (void)calculateETAWithCompletionHandler:(MKETAHandler)completionHandler
ParameterscompletionHandler
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.
AvailabilityAvailable in iOS 7.0 and later.
MKDirections Class ReferenceInstance Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
42
Declared inMKDirections.h
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirections.h
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirections.h
MKDirections Class ReferenceInstance Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirections.h
MKETAHandler
The block to use for processing travel-time information.
typedef void (^MKETAHandler)(MKETAResponse *response, NSError *error);
DiscussionThis block takes two parameters:
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirections.h
MKDirections Class ReferenceConstants
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
45
Inherits from NSObject
Conforms to NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 6.0 and later.
Declared in MKDirectionsRequest.h
Companion guide Location and Maps Programming Guide
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.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsRequest.h
departureDate
The departure date for the trip.
@property (nonatomic, retain) NSDate *departureDate;
MKDirectionsRequest Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsRequest.h
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsRequest.h
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
49
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsRequest.h
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.
AvailabilityAvailable in iOS 6.0 and later.
Declared inMKDirectionsRequest.h
Instance Methods
destination
Returns the end point for routing directions
- (MKMapItem *)destination
Return ValueThe end point for routing directions.
AvailabilityAvailable in iOS 6.0 and later.
MKDirectionsRequest Class ReferenceClass Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
50
Declared inMKDirectionsRequest.h
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.
AvailabilityAvailable in iOS 6.0 and later.
Declared inMKDirectionsRequest.h
setDestination:
Sets the end point for routing directions
- (void)setDestination:(MKMapItem *)destination
Parametersdestination
The map item that represents the end point for routing directions.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsRequest.h
MKDirectionsRequest Class ReferenceInstance Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsRequest.h
source
Returns the starting point for routing directions.
- (MKMapItem *)source
Return ValueThe starting point for routing directions.
AvailabilityAvailable in iOS 6.0 and later.
Declared inMKDirectionsRequest.h
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.
Available in iOS 7.0 and later.
Declared in MKDirectionsTypes.h.
MKDirectionsTransportTypeWalking
Directions suitable for a pedestrian.
Available in iOS 7.0 and later.
Declared in MKDirectionsTypes.h.
MKDirectionsTransportTypeAny
Directions suitable for any transportation option.
Available in iOS 7.0 and later.
Declared in MKDirectionsTypes.h.
MKDirectionsRequest Class ReferenceConstants
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
53
Inherits from NSObject
Conforms to NSObject (NSObject)
Availability Available in iOS 7.0 and later.
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)
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
54
MKDirectionsResponse Class Reference
Properties
destination
The end point of the route. (read-only)
@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.
AvailabilityAvailable in iOS 7.0 and later.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsResponse.h
source
The start point of the route. (read-only)
MKDirectionsResponse Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
55
@property (nonatomic, readonly) MKMapItem *source
DiscussionThe item in this property may contain additional details that were not included in the original item used to
create the MKDirectionsRequest object.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsResponse.h
MKDirectionsResponse Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
56
Inherits from NSObject
Conforms to NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 7.0 and later.
Declared in MKDirectionsResponse.h
Companion guide Location and Maps Programming Guide
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
The start point of the route. (read-only)
destination (page 58) property
The end point of the route. (read-only)
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
57
MKETAResponse Class Reference
Getting the Travel Time
expectedTravelTime (page 58) property
The expected travel time in seconds. (read-only)
Properties
destination
The end point of the route. (read-only)
@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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsResponse.h
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsResponse.h
MKETAResponse Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
58
source
The start point of the route. (read-only)
@property (nonatomic, readonly) MKMapItem *source
DiscussionThis item in this property may contain additional details that were not included in the original item used to
create the MKDirectionsRequest object.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKDirectionsResponse.h
MKETAResponse Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
59
Inherits from MKPolyline : MKMultiPoint : MKShape : NSObject
Conforms to MKOverlay (MKPolyline)
MKAnnotation (MKShape)
NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 7.0 and later.
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.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
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.
AvailabilityAvailable in iOS 7.0 and later.
MKGeodesicPolyline Class ReferenceClass Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
61
Declared inMKGeodesicPolyline.h
MKGeodesicPolyline Class ReferenceClass Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
62
Inherits from NSObject
Conforms to NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 6.1 and later.
Declared in MKLocalSearch.h
Companion guide Location and Maps Programming Guide
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.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 6.1 and later.
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
64
AvailabilityAvailable in iOS 6.1 and later.
Declared inMKLocalSearch.h
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.
AvailabilityAvailable in iOS 6.1 and later.
Declared inMKLocalSearch.h
startWithCompletionHandler:
Starts the search and delivers the results to the specified completion handler.
- (void)startWithCompletionHandler:(MKLocalSearchCompletionHandler)completionHandler
ParameterscompletionHandler
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 6.1 and later.
Declared inMKLocalSearch.h
Constants
MKLocalSearchCompletionHandler
A completion handler block for a search operation.
typedef void (^MKLocalSearchCompletionHandler)(MKLocalSearchResponse *response, NSError*error);
DiscussionThis block takes two parameters:
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.
AvailabilityAvailable in iOS 6.1 and later.
Declared inMKLocalSearch.h
MKLocalSearch Class ReferenceConstants
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
66
Inherits from NSObject
Conforms to NSCopying
NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 6.1 and later.
Declared in MKLocalSearchRequest.h
Companion guide Location and Maps Programming Guide
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.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 6.1 and later.
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.
AvailabilityAvailable in iOS 6.1 and later.
Declared inMKLocalSearchRequest.h
MKLocalSearchRequest Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
68
Inherits from NSObject
Conforms to NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 6.1 and later.
Declared in MKLocalSearchResponse.h
Companion guide Location and Maps Programming Guide
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)
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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).
AvailabilityAvailable in iOS 6.1 and later.
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.
AvailabilityAvailable in iOS 6.1 and later.
Declared inMKLocalSearchResponse.h
MKLocalSearchResponse Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
70
Inherits from NSObject
Conforms to NSCopying
NSSecureCoding
NSObject (NSObject)
Availability Available in iOS 7.0 and later.
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.
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKMapCamera.h
centerCoordinate
The map coordinate at the center of the map view.
MKMapCamera Class ReferenceProperties
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKMapCamera.h
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKMapCamera.h
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
73
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKMapCamera.h
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKMapCamera.h
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
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
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.
AvailabilityAvailable in iOS 7.0 and later.
Declared inMKMapCamera.h
MKMapCamera Class ReferenceClass Methods
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
75
Inherits from NSObject
Conforms to NSObject (NSObject)
Framework /System/Library/Frameworks/MapKit.framework
Availability Available in iOS 6.0 and later.
Declared in MKMapItem.h
Companion guide Location and Maps Programming Guide
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