CLLocationManager Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreLocation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
CLLocation.h
CLLocationManager.h
Related sample code

Overview

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:

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.

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. Turning off GPS hardware can lead to significant power savings.

To configure and use a CLLocationManager object to deliver events:

  1. Always check to see whether the desired services are available before starting any services and abandon the operation if they are not.

  2. Create an instance of the CLLocationManager class.

  3. Assign a custom object to the delegate property. This object must conform to the CLLocationManagerDelegate protocol.

  4. Configure any additional properties relevant to the desired service.

  5. 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. For information about the delegate methods, see CLLocationManagerDelegate Protocol Reference.

Getting the User’s Current Location

There are two options for configuring location-related services:

  • 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 OS X 10.6 and later.

  • Request events for significant location changes only, which 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.

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. The precision of the standard location services are needed by navigation applications or any application where high-precision location data or a regular stream of updates is required. However, these services typically 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, 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 lower 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 6 and later, you can defer the delivery of location data when your app is in the background. It is recommended that you use this feature in situations where your app could process the data later without any problems. For example, an app that tracks the user’s location on a hiking trail could defer updates until the user hikes a certain distance and then process the points all at once. Deferring updates helps save power by allowing your app to remain asleep for longer periods of time.

Using Regions to Monitor Boundary Crossings

In iOS 4.0 and later and OS X 10.8 and later, you can use the region-monitoring service to define the boundaries for multiple geographical regions. After registering a region using the startMonitoringForRegion: 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.

In iOS, the regions you register with the location manager persist between launches of your application. If a region crossing occurs while your iOS app is not running, the system automatically wakes it up (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.

In OS X, region monitoring works only while the app is running (either in the foreground or background) and the user’s system is awake. The system does not launch apps to deliver region-related notifications. Similarly, if the user puts the computer to sleep, the system does not deliver region monitoring notifications to your app. If the user wakes up the computer inside a monitored region, the system does deliver region notifications to your app if it is running. However, if the computer enters and exits the region before being woken up, no notification is delivered.

The region monitoring service operates independently of any location services in use by your application, and you may use it in conjunction with any of the other services. Region monitoring is not supported on all devices. Use the regionMonitoringAvailable class method to determine if region monitoring can be used.

Configuring Heading-Related Services

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 OS X.

Tasks

Accessing the Delegate

Determining the Availability of Services

Initiating Standard Location Updates

Initiating Significant Location Updates

Initiating Heading Updates

Initiating Region Monitoring

Initiating Beacon Ranging Requests

Deferring Location Updates

Getting Recently Retrieved Data

Describing Your Application’s Services to the User

Deprecated Properties and Methods

Properties

activityType

The type of user activity associated with the location updates.

@property(assign, nonatomic) CLActivityType activityType
Discussion

The location manager uses the information in this property as a cue to determine when location updates may be automatically paused. Pausing updates gives the system the opportunity to save power in situations where the user's location is not likely to be changing. For example, if the activity type is CLActivityTypeAutomotiveNavigation and no location changes have occurred recently, the radios might be powered down until movement is detected again.

The default value of this property is CLActivityTypeOther.

Availability
  • Available in iOS 6.0 and later.
Declared In
CLLocationManager.h

delegate

The delegate object to receive update events.

@property(assign, nonatomic) id<CLLocationManagerDelegate> delegate
Special Considerations

In iOS, this property is declared as nonatomic. In OS X, it is declared as atomic.

Availability
  • Available in iOS 2.0 and later.
Declared In
CLLocationManager.h

desiredAccuracy

The accuracy of the location data.

@property(assign, nonatomic) CLLocationAccuracy desiredAccuracy
Discussion

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. For example, if you need the current location only within a kilometer, you should specify kCLLocationAccuracyKilometer and not kCLLocationAccuracyBestForNavigation. 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.

Special Considerations

In iOS, this property is declared as nonatomic. In OS X, it is declared as atomic.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CLLocationManager.h

distanceFilter

The minimum distance (measured in meters) a device must move horizontally before an update event is generated.

@property(assign, nonatomic) CLLocationDistance distanceFilter
Discussion

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.

Special Considerations

In iOS, this property is declared as nonatomic. In OS X, it is declared as atomic.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CLLocationManager.h

heading

The most recently reported heading. (read-only)

@property(readonly, nonatomic) CLHeading *heading
Discussion

The value of this property is nil if heading updates have never been initiated.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

headingFilter

The minimum angular change (measured in degrees) required to generate new heading events.

@property(assign, nonatomic) CLLocationDegrees headingFilter
Discussion

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 1 degree.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
CLLocationManager.h

headingOrientation

The device orientation to use when computing heading values.

@property(assign, nonatomic) CLDeviceOrientation headingOrientation
Discussion

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

location

The most recently retrieved user location. (read-only)

@property(readonly, nonatomic) CLLocation *location
Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CLLocationManager.h

maximumRegionMonitoringDistance

The largest boundary distance that can be assigned to a region. (read-only)

@property(readonly, nonatomic) CLLocationDistance maximumRegionMonitoringDistance
Discussion

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

monitoredRegions

The set of shared regions monitored by all location manager objects. (read-only)

@property(readonly, nonatomic) NSSet *monitoredRegions
Discussion

You cannot add regions to this property directly. Instead, you must register regions by calling the startMonitoringForRegion: 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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

pausesLocationUpdatesAutomatically

A Boolean value indicating whether the location manager object may pause location updates.

@property(assign, nonatomic) BOOL pausesLocationUpdatesAutomatically
Discussion

Allowing the location manager to pause updates can improve battery life on the target device without sacrificing location data. When this property is set to YES, the location manager pauses updates (and powers down the appropriate hardware) at times when the location data is unlikely to change. For example, if the user stops for food while using a navigation app, the location manager might pause updates for a period of time. You can help the determination of when to pause location updates by assigning a value to the activityType property.

The default value of this property is YES.

Availability
  • Available in iOS 6.0 and later.
Declared In
CLLocationManager.h

rangedRegions

The set of regions currently being tracked using ranging. (read-only)

@property (readonly, nonatomic) NSSet *rangedRegions
Discussion

The objects in the set are instances of the CLBeaconRegion class.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManager.h

Class Methods

authorizationStatus

Returns the application’s authorization status for using location services.

+ (CLAuthorizationStatus)authorizationStatus
Return Value

A value indicating whether the application is authorized to use location services.

Discussion

The authorization status of a given application is managed by the system and determined by several factors. Applications must be explicitly authorized to use location services by the user and location services must themselves currently be enabled for the system. A request for user authorization is displayed automatically when your application first attempts to use location services.

Availability
  • Available in iOS 4.2 and later.
Declared In
CLLocationManager.h

deferredLocationUpdatesAvailable

Returns a Boolean value indicating whether the device supports deferred location updates.

+ (BOOL)deferredLocationUpdatesAvailable
Return Value

YES if the device supports deferred location updates or NO if it does not.

Discussion

Deferred location updates are a way for the location manager to avoid frequently waking up a background app to deliver location changes. Normally, when an app wants location updates in the background, the app must be woken up whenever a new event arrives. Waking up the app consumes power, which in some situations might be wasted if the app cannot do anything with the location information other than log it and go back to sleep anyway. Deferring location updates gives you the ability to wait until a time when your app can do something useful with the data and then process the updates all at once.

Deferred location updates require the presence of GPS hardware and may not be supported on all iOS devices.

Availability
  • Available in iOS 6.0 and later.
Declared In
CLLocationManager.h

headingAvailable

Returns a Boolean value indicating whether the location manager is able to generate heading-related events.

+ (BOOL)headingAvailable
Return Value

YES if heading data is available; NO if it is not.

Discussion

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

isMonitoringAvailableForClass:

Returns a Boolean indicating whether the device supports region monitoring using the specified class.

+ (BOOL)isMonitoringAvailableForClass:(Class)regionClass
Parameters
regionClass

A region monitoring class from the Map Kit framework. This class must be descend from the CLRegion class.

Return Value

YES if the device is capable of monitoring regions using the specified class or NO if it is not.

Discussion

The availability of region monitoring support is dependent on the hardware present on the device. This method does not take into account the availability of location services or the fact that the user might have disabled them for the app or system; you must determine your app’s authorization status separately.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManager.h

isRangingAvailable

Returns a Boolean indicating whether the device supports ranging of Bluetooth beacons.

+ (BOOL)isRangingAvailable
Return Value

YES if the device supports ranging or NO if it does not.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManager.h

locationServicesEnabled

Returns a Boolean value indicating whether location services are enabled on the device.

+ (BOOL)locationServicesEnabled
Return Value

YES if location services are enabled; NO if they are not.

Discussion

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. Location services prompts users the first time they attempt to use location-related information in an app but does not prompt for subsequent attempts. If the user denies the use of location services and you attempt to start location updates anyway, the location manager reports an error to its delegate.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

significantLocationChangeMonitoringAvailable

Returns a Boolean value indicating whether significant location change tracking is available.

+ (BOOL)significantLocationChangeMonitoringAvailable
Return Value

YES if location change monitoring is available; NO if it is not.

Discussion

This method indicates whether the device is able to report updates based on significant location changes only. (Significant location change monitoring 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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

Instance Methods

allowDeferredLocationUpdatesUntilTraveled:timeout:

Asks the location manager to defer the delivery of location updates until the specified criteria are met.

- (void)allowDeferredLocationUpdatesUntilTraveled:(CLLocationDistance)distance timeout:(NSTimeInterval)timeout
Parameters
distance

The distance (in meters) from the current location that must be travelled before event delivery resumes. To specify an unlimited distance, pass the CLLocationDistanceMax constant.

timeout

The amount of time (in seconds) from the current time that must pass before event delivery resumes. To specify an unlimited amount of time, pass the CLTimeIntervalMax constant.

Discussion

Call this method in situations where you want location data with GPS accuracy but do not need to process that data right away. If your app is in the background and the system is able to optimize its power usage, the location manager tells the GPS hardware to store new locations internally until the specified distance or timeout conditions are met. When one or both criteria are met, the location manager ends deferred locations by calling the locationManager:didFinishDeferredUpdatesWithError: method of its delegate and delivers the cached locations to the locationManager:didUpdateLocations: method. If your app is in the foreground, the location manager does not defer the deliver of events but does monitor for the specified criteria. If your app moves to the background before the criteria are met, the location manager may begin deferring the delivery of events.

Start the delivery of location updates before calling this method. The most common place to call this method is in your delegate’s locationManager:didUpdateLocations: method. After processing any new locations, call this method if you want to defer future updates until the distance or time criteria are met. If new events arrive and your app is in the background, the events are cached and their delivery is deferred appropriately.

Your delegate’s locationManager:didFinishDeferredUpdatesWithError: method is called exactly once for each time you call this method. If you call this method twice in succession, the location manager cancels the previous deferral before starting the new one. Therefore, you should keep track of whether updates are currently deferred and avoid calling this method multiple times in succession. If you want to change the deferral criteria for any reason, and therefore call this method again, be prepared to receive a kCLErrorDeferredCanceled error in your delegate’s locationManager:didFinishDeferredUpdatesWithError: method.

After calling this method, the location manager may deliver location updates even if the specified distance and timeout criteria are not met. For example, if the caches used to store deferred samples become full, the location manager may deliver the cached samples so it can collect new ones. The delivery of samples does not automatically end deferred mode for your app. The location manager resumes deferred mode when it is able to do so.

Availability
  • Available in iOS 6.0 and later.
Declared In
CLLocationManager.h

disallowDeferredLocationUpdates

Cancels the deferral of location updates for this app.

- (void)disallowDeferredLocationUpdates
Discussion

Call this method if you previously deferred location event delivery using the allowDeferredLocationUpdatesUntilTraveled:timeout: method and now want to resume the delivery of events at normal intervals.

Availability
  • Available in iOS 6.0 and later.
Declared In
CLLocationManager.h

dismissHeadingCalibrationDisplay

Dismisses the heading calibration view from the screen immediately.

- (void)dismissHeadingCalibrationDisplay
Discussion

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.

Availability
  • Available in iOS 3.0 and later.
Declared In
CLLocationManager.h

requestStateForRegion:

Retrieves the state of a region asynchronously.

- (void)requestStateForRegion:(CLRegion *)region
Parameters
region

The region whose state you want to know. This object must be an instance of one of the standard region subclasses provided by Map Kit. You cannot use this method to determine the state of custom regions you define yourself.

Discussion

This method performs the request asynchronously and delivers the results to the location manager’s delegate. You must implement the locationManager:didDetermineState:forRegion: method in the delegate to receive the results.

If the region parameter contains an unknown type of region object, this method does nothing.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManager.h

startMonitoringForRegion:

Starts monitoring the specified region.

- (void)startMonitoringForRegion:(CLRegion *)region
Parameters
region

The region object that defines the boundary to monitor. This parameter must not be nil.

Discussion

You must call this method once 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.

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.

An app can register up to 20 regions at a time. In order to report region changes in a timely manner, the region monitoring service requires network connectivity.

In iOS 6, regions with a radius between 1 and 400 meters work better on iPhone 4S or later devices. (In iOS 5, regions with a radius between 1 and 150 meters work better on iPhone 4S and later devices.) On these devices, an app can expect to receive the appropriate region entered or region exited notification within 3 to 5 minutes on average, if not sooner.

Availability
  • Available in iOS 5.0 and later.
Declared In
CLLocationManager.h

startMonitoringSignificantLocationChanges

Starts the generation of updates based on significant location changes.

- (void)startMonitoringSignificantLocationChanges
Discussion

This method initiates the delivery of location events asynchronously, returning shortly after you call it. Location events are delivered to your delegate’s locationManager:didUpdateLocations: 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 locationManager:didUpdateLocations: 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:didUpdateLocations: method, it should also implement the locationManager:didFailWithError: method to respond to potential errors.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

startRangingBeaconsInRegion:

Starts the delivery of notifications for beacons in the specified region.

- (void)startRangingBeaconsInRegion:(CLBeaconRegion *)region
Parameters
region

The region object that defines the identifying information for the targeted beacons. The number of beacons represented by this region object depends on which identifier values you use to initialize it. Beacons must match all of the identifiers you specify. This method copies the region information it needs from the object you provide.

Discussion

Once registered, the location manager reports any encountered beacons to its delegate by calling the locationManager:didRangeBeacons:inRegion: method. If there is an error registering the specified beacon region, the location manager calls its delegate’s locationManager:rangingBeaconsDidFailForRegion:withError: method and provides the appropriate error information.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManager.h

startUpdatingHeading

Starts the generation of updates that report the user’s current heading.

- (void)startUpdatingHeading
Discussion

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.

Availability
  • Available in iOS 3.0 and later.
Declared In
CLLocationManager.h

startUpdatingLocation

Starts the generation of updates that report the user’s current location.

- (void)startUpdatingLocation
Discussion

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:didUpdateLocations: method. (In iOS 5 and earlier, the location manager calls the locationManager:didUpdateToLocation:fromLocation: method instead.) 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:didUpdateLocations: method, it should also implement the locationManager:didFailWithError: method to respond to potential errors.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CLLocationManager.h

stopMonitoringForRegion:

Stops monitoring the specified region.

- (void)stopMonitoringForRegion:(CLRegion *)region
Parameters
region

The region object currently being monitored. This parameter must not be nil.

Discussion

If the specified region object is not currently being monitored, this method has no effect.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

stopMonitoringSignificantLocationChanges

Stops the delivery of location events based on significant location changes.

- (void)stopMonitoringSignificantLocationChanges
Discussion

Use this method to stop the delivery of location events that was started using the startMonitoringSignificantLocationChanges method.

Availability
  • Available in iOS 4.0 and later.
Declared In
CLLocationManager.h

stopRangingBeaconsInRegion:

Stops the delivery of notifications for the specified beacon region.

- (void)stopRangingBeaconsInRegion:(CLBeaconRegion *)region
Parameters
region

The region that identifies the beacons. The object you specify need not be the exact same object that you registered but the beacon attributes should be the same.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManager.h

stopUpdatingHeading

Stops the generation of heading updates.

- (void)stopUpdatingHeading
Discussion

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.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
CLLocationManager.h

stopUpdatingLocation

Stops the generation of location updates.

- (void)stopUpdatingLocation
Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CLLocationManager.h

Constants

CLAuthorizationStatus

These constants indicate whether the application is authorized to use location services.

typedef enum {
   kCLAuthorizationStatusNotDetermined = 0,
   kCLAuthorizationStatusRestricted,
   kCLAuthorizationStatusDenied,
   kCLAuthorizationStatusAuthorized
} CLAuthorizationStatus;
Constants
kCLAuthorizationStatusNotDetermined

The user has not yet made a choice regarding whether this application can use location services.

Available in iOS 4.2 and later.

Declared in CLLocationManager.h.

kCLAuthorizationStatusRestricted

This application is not authorized to use location services. The user cannot change this application’s status, possibly due to active restrictions such as parental controls being in place.

Available in iOS 4.2 and later.

Declared in CLLocationManager.h.

kCLAuthorizationStatusDenied

The user explicitly denied the use of location services for this application or location services are currently disabled in Settings.

Available in iOS 4.2 and later.

Declared in CLLocationManager.h.

kCLAuthorizationStatusAuthorized

This application is authorized to use location services.

Available in iOS 4.2 and later.

Declared in CLLocationManager.h.

Deferred Update Constants

Constants for specifying maximum values during deferred updates.

extern const CLLocationDistance CLLocationDistanceMax;
extern const NSTimeInterval CLTimeIntervalMax;
Constants
CLLocationDistanceMax

A value representing an unlimited distance.

Available in iOS 6.0 and later.

Declared in CLLocation.h.

CLTimeIntervalMax

A value representing an unlimited amount of time.

Available in iOS 6.0 and later.

Declared in CLLocation.h.

CLActivityType

These constants indicate the type of activity associated with location updates.

enum {
   CLActivityTypeOther = 1,
   CLActivityTypeAutomotiveNavigation,
   CLActivityTypeFitness,
   CLActivityTypeOtherNavigation,
};
typedef NSInteger CLActivityType;
Constants
CLActivityTypeOther

The location manager is being used for an unknown activity.

Available in iOS 6.0 and later.

Declared in CLLocationManager.h.

CLActivityTypeAutomotiveNavigation

The location manager is being used specifically during vehicular navigation to track location changes to the automobile. This activity might cause location updates to be paused only when the vehicle does not move for an extended period of time.

Available in iOS 6.0 and later.

Declared in CLLocationManager.h.

CLActivityTypeFitness

The location manager is being used to track any pedestrian-related activity. This activity might cause location updates to be paused only when the user does not move a significant distance over a period of time.

Available in iOS 6.0 and later.

Declared in CLLocationManager.h.

CLActivityTypeOtherNavigation

The location manager is being used to track movements for other types of vehicular navigation that are not automobile related. For example, you would use this to track navigation by boat, train, or plane. Do not use this type for pedestrian navigation tracking. This activity might cause location updates to be paused only when the vehicle does not move a significant distance over a period of time.

Available in iOS 6.0 and later.

Declared in CLLocationManager.h.