| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreLocation.framework |
| Availability | Available in iOS 2.0 and later. |
| Declared in | CLError.h CLErrorDomain.h CLHeading.h CLLocation.h CLLocationManager.h |
The CLLocationManager class defines the interface for configuring the delivery of location- and heading-related events to your application. You use an instance of this class to establish the parameters that determine when location and heading events should be delivered and to start and stop the actual delivery of those events. You can also use a location manager object to retrieve the most recent location and heading data.
A location manager object provides support for the following location-related activities:
Tracking large or small changes in the user’s current location with a configurable degree of accuracy. (iOS and Mac OS X)
Reporting heading changes from the onboard compass. (iOS only)
Monitoring distinct regions of interest and generating location events when the user enters or leaves those regions. (iOS only)
Some location services require the presence of specific hardware on the given device. For example, heading information is available only for devices that contain a hardware compass. This class defines several methods that you can use to determine which services are currently available.
Important: In addition to hardware not being available, the user has the option of denying an application’s access to location service data. During its initial uses by an application, the Core Location framework prompts the user to confirm that using the location service is acceptable. If the user denies the request, the CLLocationManager object reports an appropriate error to its delegate during future requests.
For the services you do use, you should configure any properties associated with that service accurately. The location manager object manages power aggressively by turning off hardware when it is not needed. For example, setting the desired accuracy for location events to one kilometer gives the location manager the flexibility to turn off GPS hardware and rely solely on the WiFi or cell radios. This can lead to significant power savings.
To configure and use a CLLocationManager object to deliver events:
Always check to see whether the desired services are available before starting any services and abandon the operation if they are not.
Create an instance of the CLLocationManager class.
Assign a custom object to the delegate property. This object must conform to the CLLocationManagerDelegate protocol.
Configure any additional properties relevant to the desired service.
Call the appropriate start method to begin the delivery of events.
All location- and heading-related updates are delivered to the associated delegate object, which is a custom object that you provide. The delegate object must conform to the CLLocationManagerDelegate protocol and implement the appropriate methods. For information about the methods of this protocol, see CLLocationManagerDelegate Protocol Reference.
There are two options for configuring location-related services:
You can use the standard location services, which allow you to specify the desired accuracy of the location data and receive updates as the location changes. Standard location services are available in all versions of iOS and in Mac OS X 10.6 and later.
You can request events for significant location changes only. This provides a more limited set of tracking options but offers tremendous power savings and the ability to receive location updates even if your application is not running. This service is available only in iOS 4.0 and later and requires a device with a cellular radio.
You start standard location services by calling the startUpdatingLocation method. This service is most appropriate for applications that need more fine-grained control over the delivery of location events. Specifically, it takes into account the values in the desiredAccuracy and distanceFilter property to determine when to deliver new events. This is most appropriate for navigation applications or any application where high-precision location data or a regular stream of updates is required. However, these services typically also require the location-tracking hardware to be enabled for longer periods of time, which can result in higher power usage.
For applications that do not need a regular stream of location events, you should consider using the startMonitoringSignificantLocationChanges method to start the delivery of events instead. This method is more appropriate for the majority of applications that just need an initial user location fix and need updates only when the user moves a significant distance. This interface delivers new events only when it detects changes to the device’s associated cell towers, resulting in less frequent updates and significantly better power usage.
Regardless of which location service you use, location data is reported to your application via the location manager’s associated delegate object. Because it can take several seconds to return an initial location, the location manager typically delivers the previously cached location data immediately and then delivers more up-to-date location data as it becomes available. Therefore it is always a good idea to check the timestamp of any location object before taking any actions. If both location services are enabled simultaneously, they deliver events using the same set of delegate methods.
In iOS 4.0 and later, you can use the region monitoring service to define the boundaries for multiple geographical regions. After registering a region using the startMonitoringForRegion:desiredAccuracy: method, the location manager tracks movement across the region’s boundary and reports that movement to its delegate. You might use region monitoring to alert the user to approaching landmarks or to provide other relevant information. For example, upon approaching a dry cleaners, an application could notify the user to pick up any clothes that had been dropped off and are now ready.
The regions you register with the location manager persist between launches of your application. If a region crossing occurs while your application is not running, the system automatically wakes up your application (or relaunches it) in the background so that it can process the event. When relaunched, all of the regions you configured previously are made available in the monitoredRegions property of any location manager objects you create.
The region monitoring service operates independently of any location services in use by your application. You may use it in conjunction with any of the other services. Region monitoring is not available in Mac OS X and is not supported on all devices. Use the regionMonitoringAvailable and regionMonitoringEnabled class methods to determine if region monitoring can be used.
In iOS, a device with the appropriate hardware may also report heading information. When the value in the headingAvailable property is YES, you can use a location manager object to retrieve heading information. To begin the delivery of heading-related events, assign a delegate to the location manager object and call the location manager’s startUpdatingHeading method. If location updates are also enabled, the location manager returns both the true heading and magnetic heading values. If location updates are not enabled, the location manager returns only the magnetic heading value. These features are not available in Mac OS X.
delegate property
+ locationServicesEnabled
+ significantLocationChangeMonitoringAvailable
+ headingAvailable
+ regionMonitoringAvailable
+ regionMonitoringEnabled
headingAvailable property Deprecated in iOS 4.0
locationServicesEnabled property Deprecated in iOS 4.0
– startUpdatingLocation
– stopUpdatingLocation
distanceFilter property
desiredAccuracy property
– startUpdatingHeading
– stopUpdatingHeading
– dismissHeadingCalibrationDisplay
headingFilter property
headingOrientation property
– startMonitoringForRegion:desiredAccuracy:
– stopMonitoringForRegion:
monitoredRegions property
maximumRegionMonitoringDistance property
purpose property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
The delegate object you want to receive update events.
@property(assign, nonatomic) id<CLLocationManagerDelegate> delegate
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hThe desired accuracy of the location data.
@property(assign, nonatomic) CLLocationAccuracy desiredAccuracy
The receiver does its best to achieve the requested accuracy; however, the actual accuracy is not guaranteed.
You should assign a value to this property that is appropriate for your usage scenario. In other words, if you need the current location only within a few kilometers, you should not specify kCLLocationAccuracyBest for the accuracy. Determining a location with greater accuracy requires more time and more power.
When requesting high-accuracy location data, the initial event delivered by the location service may not have the accuracy you requested. The location service delivers the initial event as quickly as possible. It then continues to determine the location with the accuracy you requested and delivers additional events, as necessary, when that data is available.
The default value of this property is kCLLocationAccuracyBest.
This property is used only in conjunction with the standard location services and is not used when monitoring significant location changes.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hThe minimum distance (measured in meters) a device must move laterally before an update event is generated.
@property(assign, nonatomic) CLLocationDistance distanceFilter
This distance is measured relative to the previously delivered location. Use the value kCLDistanceFilterNone to be notified of all movements. The default value of this property is kCLDistanceFilterNone.
This property is used only in conjunction with the standard location services and is not used when monitoring significant location changes.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hThe most recently reported heading. (read-only)
@property(readonly, nonatomic) CLHeading *heading
The value of this property is nil if heading updates have never been initiated.
CLLocationManager.hThe minimum angular change (measured in degrees) required to generate new heading events.
@property(assign, nonatomic) CLLocationDegrees headingFilter
The angular distance is measured relative to the last delivered heading event. Use the value kCLHeadingFilterNone to be notified of all movements. The default value of this property is kCLHeadingFilterNone.
CLLocationManager.hThe device orientation to use when computing heading values.
@property(assign, nonatomic) CLDeviceOrientation headingOrientation
When computing heading values, the location manager assumes that the top of the device in portrait mode represents due north (0 degrees) by default. For applications that run in other orientations, this may not always be the most convenient orientation. This property allows you to specify which device orientation you want the location manager to use as the reference point for due north.
Although you can set the value of this property to CLDeviceOrientationUnknown, CLDeviceOrientationFaceUp, or CLDeviceOrientationFaceDown, doing so has no effect on the orientation reference point. The original reference point is retained instead.
Changing the value in this property affects only those heading values reported after the change is made.
CLLocationManager.hThe most recently retrieved user location. (read-only)
@property(readonly, nonatomic) CLLocation *location
The value of this property is nil if no location data has ever been retrieved.
In iOS 4.0 and later, this property may contain a more recent location object at launch time. Specifically, if significant location updates are running and your application is terminated, this property is updated with the most recent location data when your application is relaunched (and you create a new location manager object). This location data may be more recent than the last location event processed by your application.
It is always a good idea to check the timestamp of the location stored in this property. If the receiver is currently gathering location data, but the minimum distance filter is large, the returned location might be relatively old. If it is, you can stop the receiver and start it again to force an update.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hThe largest boundary distance that can be assigned to a region. (read-only)
@property(readonly, nonatomic) CLLocationDistance maximumRegionMonitoringDistance
This property defines the largest boundary distance allowed from a region’s center point. Attempting to monitor a region with a distance larger than this value causes the location manager to send a kCLErrorRegionMonitoringFailure error to the delegate.
If region monitoring is unavailable or not supported, the value in this property is -1.
CLLocationManager.hThe set of shared regions monitored by all location manager objects. (read-only)
@property(readonly, nonatomic) NSSet *monitoredRegions
You cannot add regions to this property directly. Instead, you must register regions by calling the startMonitoringForRegion:desiredAccuracy: method. The regions in this property are shared by all instances of the CLLocationManager class in your application.
The objects in this set may not necessarily be the same objects you specified at registration time. Only the region data itself is maintained by the system. Therefore, the only way to uniquely identify a registered region is using its identifier property.
The location manager persists region data between launches of your application. If your application is terminated and then relaunched, the contents of this property are repopulated with region objects that contain the previously registered data.
CLLocationManager.hAn application-provided string that describes the reason for using location services.
@property(copy, nonatomic) NSString *purpose
If this property is not nil and the system needs to ask for the user’s consent to use location services, it displays the provided string. You can use this string to explain why your application is using location services.
You must set the value of this property prior to starting any location services. Because the string is ultimately displayed to the user, you should always load it from a localized strings file.
CLLocationManager.hReturns a Boolean value indicating whether the location manager is able to generate heading-related events.
+ (BOOL)headingAvailable
YES if heading data is available or NO if it is not.
Heading data may not be available on all iOS-based devices. You should check the value returned by this method before asking the location manager to deliver heading-related events.
CLLocationManager.hReturns a Boolean value indicating whether location services are enabled on the device.
+ (BOOL)locationServicesEnabled
YES if location services are enabled or NO if they are not.
The user can enable or disable location services from the Settings application by toggling the Location Services switch in General.
You should check the return value of this method before starting location updates to determine whether the user has location services enabled for the current device. If this method returns NO and you start location updates anyway, the Core Location framework prompts the user with a confirmation panel asking whether location services should be reenabled.
CLLocationManager.hReturns a Boolean indicating whether region monitoring is supported on the current device.
+ (BOOL)regionMonitoringAvailable
YES if region monitoring is available or NO if it is not.
Support for region monitoring may not be available on all devices and models. You should check the value of this property before attempting to set up any regions or initiate region monitoring.
Even if region monitoring support is present on a device, it may still be unavailable because the user disabled it for the current application or for all applications.
CLLocationManager.hReturns a Boolean indicating whether region monitoring is currently enabled.
+ (BOOL)regionMonitoringEnabled
YES if region monitoring is available and is currently enabled or NO if it is unavailable or not enabled.
The user can enable or disable location services (including region monitoring) altogether from the Settings application by toggling the switch in Settings > General > Location Services.
You should check the return value of this method before starting region monitoring updates to determine if the user currently allows location services to be used at all. If this method returns NO and you start region monitoring updates anyway, the Core Location framework prompts the user with a confirmation panel asking whether location services should be reenabled.
This method does not check to see if region monitoring capabilities are actually supported by the device. Therefore, you should also check the return value of the regionMonitoringAvailable class method before attempting to start region monitoring services.
CLLocationManager.hReturns a Boolean value indicating whether significant location change tracking is available.
+ (BOOL)significantLocationChangeMonitoringAvailable
YES if location change monitoring is available or NO if it is not.
This method indicates whether the device is able to report updates based on significant location changes only. (This primarily involves detecting changes in the cell tower currently associated with the device.) This capability provides tremendous power savings for applications that want to track a user’s approximate location and do not need highly accurate position information.
CLLocationManager.hDismisses the heading calibration view from the screen immediately.
- (void)dismissHeadingCalibrationDisplay
Core Location uses the heading calibration alert to calibrate the available heading hardware as needed. The display of this view is automatic, assuming your delegate supports displaying the view at all. If the view is displayed, you can use this method to dismiss it after an appropriate amount of time to ensure that your application’s user interface is not unduly disrupted.
CLLocationManager.hStarts monitoring the specified region for boundary crossings.
- (void)startMonitoringForRegion:(CLRegion *)regiondesiredAccuracy:(CLLocationAccuracy)accuracy
The region object that defines the boundary to monitor. This parameter must not be nil.
The distance past the border (measured in meters) at which to generate notifications. You can use this value to prevent the delivery of multiple notifications when the user is close to the border’s edge.
You must call this method separately for each region you want to monitor. If an existing region with the same identifier is already being monitored by the application, the old region is replaced by the new one. The regions you add using this method are shared by all location manager objects in your application and stored in the monitoredRegions property.
If you begin monitoring a region and your application is subsequently terminated, the system automatically relaunches it into the background if the region boundary is crossed. In such a case, the options dictionary passed to the application:didFinishLaunchingWithOptions: method of your application delegate contains the UIApplicationLaunchOptionsLocationKey key to indicate that your application was launched because of a location-related event. In addition, creating a new location manager and assigning a delegate results in the delivery of the corresponding region messages. The newly created location manager’s location property also contains the current location even if location services are not enabled.
Region events are delivered to the locationManager:didEnterRegion: and locationManager:didExitRegion: methods of your delegate. If there is an error, the location manager calls the locationManager:monitoringDidFailForRegion:withError: method of your delegate instead.
CLLocationManager.hStarts the generation of updates based on significant location changes.
- (void)startMonitoringSignificantLocationChanges
This method initiates the delivery of location events asynchronously, returning shortly after you call it. Location events are delivered to your delegate’s locationManager:didUpdateToLocation:fromLocation: method. The first event to be delivered is usually the most recently cached location event (if any) but may be a newer event in some circumstances. Obtaining a current location fix may take several additional seconds, so be sure to check the timestamps on the location events in your delegate method.
After returning a current location fix, the receiver generates update events only when a significant change in the user’s location is detected. For example, it might generate a new event when the device becomes associated with a different cell tower. It does not rely on the value in the distanceFilter property to generate events. Calling this method several times in succession does not automatically result in new events being generated. Calling stopMonitoringSignificantLocationChanges in between, however, does cause a new initial event to be sent the next time you call this method.
If you start this service and your application is subsequently terminated, the system automatically relaunches the application into the background if a new event arrives. In such a case, the options dictionary passed to the application:didFinishLaunchingWithOptions: method of your application delegate contains the key UIApplicationLaunchOptionsLocationKey to indicate that your application was launched because of a location event. Upon relaunch, you must still configure a location manager object and call this method to continue receiving location events. When you restart location services, the current event is delivered to your delegate immediately. In addition, the location property of your location manager object is populated with the most recent location object even before you start location services.
In addition to your delegate object implementing the locationManager:didUpdateToLocation:fromLocation: method, it should also implement the locationManager:didFailWithError: method to respond to potential errors.
CLLocationManager.hStarts the generation of updates that report the user’s current heading.
- (void)startUpdatingHeading
This method returns immediately. Calling this method when the receiver is stopped causes it to obtain an initial heading and notify your delegate. After that, the receiver generates update events when the value in the headingFilter property is exceeded.
Before calling this method, you should always check the headingAvailable property to see whether heading information is supported on the current device. If heading information is not supported, calling this method has no effect and does not result in the delivery of events to your delegate.
Calling this method several times in succession does not automatically result in new events being generated. Calling stopUpdatingHeading in between, however, does cause a new initial event to be sent the next time you call this method.
If you start this service and your application is suspended, the system stops the delivery of events until your application starts running again (either in the foreground or background). If your application is terminated, the delivery of new heading events stops altogether and must be restarted by your code when the application is relaunched.
Heading events are delivered to the locationManager:didUpdateHeading: method of your delegate. If there is an error, the location manager calls the locationManager:didFailWithError: method of your delegate instead.
CLLocationManager.hStarts the generation of updates that report the user’s current location.
- (void)startUpdatingLocation
This method returns immediately. Calling this method causes the location manager to obtain an initial location fix (which may take several seconds) and notify your delegate by calling its locationManager:didUpdateToLocation:fromLocation: method. After that, the receiver generates update events primarily when the value in the distanceFilter property is exceeded. Updates may be delivered in other situations though. For example, the receiver may send another notification if the hardware gathers a more accurate location reading.
Calling this method several times in succession does not automatically result in new events being generated. Calling stopUpdatingLocation in between, however, does cause a new initial event to be sent the next time you call this method.
If you start this service and your application is suspended, the system stops the delivery of events until your application starts running again (either in the foreground or background). If your application is terminated, the delivery of new location events stops altogether. Therefore, if your application needs to receive location events while in the background, it must include the UIBackgroundModes key (with the location value) in its Info.plist file.
In addition to your delegate object implementing the locationManager:didUpdateToLocation:fromLocation: method, it should also implement the locationManager:didFailWithError: method to respond to potential errors.
CLLocationManager.hStops monitoring the specified region.
- (void)stopMonitoringForRegion:(CLRegion *)region
The region object currently being monitored. This parameter must not be nil.
If the specified region object is not currently being monitored, this method has no effect.
CLLocationManager.hStops the delivery of location events based on significant location changes.
- (void)stopMonitoringSignificantLocationChanges
Use this method to stop the delivery of location events that was started using the startMonitoringSignificantLocationChanges method.
CLLocationManager.hStops the generation of heading updates.
- (void)stopUpdatingHeading
You should call this method whenever your code no longer needs to receive heading-related events. Disabling event delivery gives the receiver the option of disabling the appropriate hardware (and thereby saving power) when no clients need location data. You can always restart the generation of heading updates by calling the startUpdatingHeading method again.
CLLocationManager.hStops the generation of location updates.
- (void)stopUpdatingLocation
You should call this method whenever your code no longer needs to receive location-related events. Disabling event delivery gives the receiver the option of disabling the appropriate hardware (and thereby saving power) when no clients need location data. You can always restart the generation of location updates by calling the startUpdatingLocation method again.
CLLocationManager.hA distance measurement (in meters) from an existing location.
typedef double CLLocationDistance;
CLLocation.hThis constant indicates the minimum distance required before an event is generated.
extern const CLLocationDistance kCLDistanceFilterNone;
kCLDistanceFilterNoneAll movements are reported.
Available in iOS 2.0 and later.
Declared in CLLocation.h.
This constant indicates the minimum heading change before an event is generated.
const CLLocationDegrees kCLHeadingFilterNone;
kCLHeadingFilterNoneAll heading changes are reported.
Available in iOS 3.0 and later.
Declared in CLHeading.h.
Error codes returned by the location manager object.
typedef enum {
kCLErrorLocationUnknown = 0,
kCLErrorDenied,
kCLErrorNetwork,
kCLErrorHeadingFailure,
kCLErrorRegionMonitoringDenied,
kCLErrorRegionMonitoringFailure,
kCLErrorRegionMonitoringSetupDelayed
} CLError;
kCLErrorLocationUnknownThe location manager was unable to obtain a location value right now.
Available in iOS 2.0 and later.
Declared in CLError.h.
kCLErrorDeniedAccess to the location service was denied by the user.
Available in iOS 2.0 and later.
Declared in CLError.h.
kCLErrorNetworkThe network was unavailable or a network error occurred.
Available in iOS 3.0 and later.
Declared in CLError.h.
kCLErrorHeadingFailureThe heading could not be determined.
Available in iOS 3.0 and later.
Declared in CLError.h.
kCLErrorRegionMonitoringDeniedAccess to the region monitoring service was denied by the user.
Available in iOS 4.0 and later.
Declared in CLError.h.
kCLErrorRegionMonitoringFailureA registered region cannot be monitored.
Available in iOS 4.0 and later.
Declared in CLError.h.
kCLErrorRegionMonitoringSetupDelayedCore Location could not initialize the region monitoring feature immediately.
Available in iOS 4.0 and later.
Declared in CLError.h.
Errors are delivered to the delegate using an NSError object.
The domain for Core Location errors.
extern NSString *const kCLErrorDomain;
kCLErrorDomainThe domain for Core Location errors. This value is used in the NSError class.
Available in iOS 2.0 and later.
Declared in CLErrorDomain.h.
The physical orientation of the device.
typedef enum {
CLDeviceOrientationUnknown = 0,
CLDeviceOrientationPortrait,
CLDeviceOrientationPortraitUpsideDown,
CLDeviceOrientationLandscapeLeft,
CLDeviceOrientationLandscapeRight,
CLDeviceOrientationFaceUp,
CLDeviceOrientationFaceDown
} CLDeviceOrientation;
CLDeviceOrientationUnknownThe orientation is currently not known.
Available in iOS 4.0 and later.
Declared in CLLocationManager.h.
CLDeviceOrientationPortraitThe device is in portrait mode, with the device held upright and the home button at the bottom.
Available in iOS 4.0 and later.
Declared in CLLocationManager.h.
CLDeviceOrientationPortraitUpsideDownThe device is in portrait mode but upside down, with the device held upright and the home button at the top.
Available in iOS 4.0 and later.
Declared in CLLocationManager.h.
CLDeviceOrientationLandscapeLeftThe device is in landscape mode, with the device held upright and the home button on the right side.
Available in iOS 4.0 and later.
Declared in CLLocationManager.h.
CLDeviceOrientationLandscapeRightThe device is in landscape mode, with the device held upright and the home button on the left side.
Available in iOS 4.0 and later.
Declared in CLLocationManager.h.
CLDeviceOrientationFaceUpThe device is held parallel to the ground with the screen facing upwards.
Available in iOS 4.0 and later.
Declared in CLLocationManager.h.
CLDeviceOrientationFaceDownThe device is held parallel to the ground with the screen facing downwards.
Available in iOS 4.0 and later.
Declared in CLLocationManager.h.
Last updated: 2010-05-14