iOS Developer Library

Developer

CoreLocation Framework Reference CLLocationManager Class Reference

Options
Deployment Target:

On This Page
Language:

CLLocationManager

The CLLocationManager class is the central point for configuring the delivery of location- and heading-related events to your app. 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. More...

Inheritance


Conforms To


Import Statement


import CoreLocation @import CoreLocation;

Availability


Available in iOS 2.0 and later.
  • Requests permission to use location services while the app is in the foreground.

    Declaration

    Swift

    func requestWhenInUseAuthorization()

    Objective-C

    - (void)requestWhenInUseAuthorization

    Discussion

    When the current authorization status is kCLAuthorizationStatusNotDetermined, this method runs asynchronously and prompts the user to grant permission to the app to use location services. The user prompt contains the text from the NSLocationWhenInUseUsageDescription key in your app’s Info.plist file, and the presence of that key is required when calling this method. After the status is determined, the location manager delivers the results to the delegate’s locationManager:didChangeAuthorizationStatus: method. If the current authorization status is anything other than kCLAuthorizationStatusNotDetermined, this method does nothing and does not call the locationManager:didChangeAuthorizationStatus: method.

    You must call this method or the requestAlwaysAuthorization method prior to using location services. If the user grants “when-in-use” authorization to your app, your app can start most (but not all) location services while it is in the foreground. (Apps cannot use any services that automatically relaunch the app, such as region monitoring or the significant location change service.) When started in the foreground, services continue to run in the background if your app has enabled background location updates in the Capabilities tab of your Xcode project. Attempts to start location services while your app is running in the background will fail. The system displays a location-services indicator in the status bar when your app moves to the background with active location services.

    For more information about the NSLocationWhenInUseUsageDescription key, see Information Property List Key Reference.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 8.0 and later.

  • Requests permission to use location services whenever the app is running.

    Declaration

    Swift

    func requestAlwaysAuthorization()

    Objective-C

    - (void)requestAlwaysAuthorization

    Discussion

    When the current authorization status is kCLAuthorizationStatusNotDetermined, this method runs asynchronously and prompts the user to grant permission to the app to use location services. The user prompt contains the text from the NSLocationAlwaysUsageDescription key in your app’s Info.plist file, and the presence of that key is required when calling this method. After the status is determined, the location manager delivers the results to the delegate’s locationManager:didChangeAuthorizationStatus: method. If the current authorization status is anything other than kCLAuthorizationStatusNotDetermined, this method does nothing and does not call the locationManager:didChangeAuthorizationStatus: method.

    You must call this method or the requestWhenInUseAuthorization method prior to using location services. When the user grants “Always” authorization to your app, your app can start any of the available location services while your app is running in the foreground or background. In addition, services that allow your app to be launched in the background continue to do so.

    For more information about the NSLocationAlwaysUsageDescription key, see Information Property List Key Reference.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 8.0 and later.

  • Returns the app’s authorization status for using location services.

    Declaration

    Swift

    class func authorizationStatus() -> CLAuthorizationStatus

    Objective-C

    + (CLAuthorizationStatus)authorizationStatus

    Return Value

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

    Discussion

    The authorization status of a given app is managed by the system and determined by several factors. Apps 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 app first attempts to use location services.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.2 and later.

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

    Declaration

    Swift

    class func locationServicesEnabled() -> Bool

    Objective-C

    + (BOOL)locationServicesEnabled

    Return Value

    YEStrue if location services are enabled; NOfalse if they are not.

    Discussion

    The user can enable or disable location services from the Settings app 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    class func deferredLocationUpdatesAvailable() -> Bool

    Objective-C

    + (BOOL)deferredLocationUpdatesAvailable

    Return Value

    YEStrue if the device supports deferred location updates or NOfalse 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    class func significantLocationChangeMonitoringAvailable() -> Bool

    Objective-C

    + (BOOL)significantLocationChangeMonitoringAvailable

    Return Value

    YEStrue if location change monitoring is available; NOfalse if it is not.

    Discussion

    This method indicates whether the device is able to report updates based on significant location changes only. This capability provides tremendous power savings for apps that want to track a user’s approximate location and do not need highly accurate position information.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    class func headingAvailable() -> Bool

    Objective-C

    + (BOOL)headingAvailable

    Return Value

    YEStrue if heading data is available; NOfalse 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    class func isMonitoringAvailableForClass(_ regionClass: AnyClass!) -> Bool

    Objective-C

    + (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

    YEStrue if the device is capable of monitoring regions using the specified class or NOfalse 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    class func isRangingAvailable() -> Bool

    Objective-C

    + (BOOL)isRangingAvailable

    Return Value

    YEStrue if the device supports ranging or NOfalse if it does not.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • delegate delegate Property

    The delegate object to receive update events.

    Declaration

    Swift

    unowned(unsafe) var delegate: CLLocationManagerDelegate!

    Objective-C

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

    Special Considerations

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func startUpdatingLocation()

    Objective-C

    - (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 app is suspended, the system stops the delivery of events until your app starts running again (either in the foreground or background). If your app is terminated, the delivery of new location events stops altogether. Therefore, if your app 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

  • Stops the generation of location updates.

    Declaration

    Swift

    func stopUpdatingLocation()

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var pausesLocationUpdatesAutomatically: Bool

    Objective-C

    @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 YEStrue, 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 YEStrue.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

    See Also

    activityType

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

    Declaration

    Swift

    var distanceFilter: CLLocationDistance

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

  • The accuracy of the location data.

    Declaration

    Swift

    var desiredAccuracy: CLLocationAccuracy

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

  • The type of user activity associated with the location updates.

    Declaration

    Swift

    var activityType: CLActivityType

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

  • Starts the generation of updates based on significant location changes.

    Declaration

    Swift

    func startMonitoringSignificantLocationChanges()

    Objective-C

    - (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. 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 app is subsequently terminated, the system automatically relaunches the app into the background if a new event arrives. In such a case, the options dictionary passed to the application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: methods of your app delegate contains the key UIApplicationLaunchOptionsLocationKey to indicate that your app 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func stopMonitoringSignificantLocationChanges()

    Objective-C

    - (void)stopMonitoringSignificantLocationChanges

    Discussion

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func startUpdatingHeading()

    Objective-C

    - (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 app is suspended, the system stops the delivery of events until your app starts running again (either in the foreground or background). If your app is terminated, the delivery of new heading events stops altogether and must be restarted by your code when the app 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 3.0 and later.

  • Stops the generation of heading updates.

    Declaration

    Swift

    func stopUpdatingHeading()

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 3.0 and later.

  • Dismisses the heading calibration view from the screen immediately.

    Declaration

    Swift

    func dismissHeadingCalibrationDisplay()

    Objective-C

    - (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 app’s user interface is not unduly disrupted.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    var headingFilter: CLLocationDegrees

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 3.0 and later.

  • The device orientation to use when computing heading values.

    Declaration

    Swift

    var headingOrientation: CLDeviceOrientation

    Objective-C

    @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 apps 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

  • Starts monitoring the specified region.

    Declaration

    Swift

    func startMonitoringForRegion(_ region: CLRegion!)

    Objective-C

    - (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 app, 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 app 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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.

  • Stops monitoring the specified region.

    Declaration

    Swift

    func stopMonitoringForRegion(_ region: CLRegion!)

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    @NSCopying var monitoredRegions: NSSet! { get }

    Objective-C

    @property(readonly, nonatomic, copy) 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 app.

    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 app. If your app is terminated and then relaunched, the contents of this property are repopulated with region objects that contain the previously registered data.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var maximumRegionMonitoringDistance: CLLocationDistance { get }

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func startRangingBeaconsInRegion(_ region: CLBeaconRegion!)

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • Stops the delivery of notifications for the specified beacon region.

    Declaration

    Swift

    func stopRangingBeaconsInRegion(_ region: CLBeaconRegion!)

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • Retrieves the state of a region asynchronously.

    Declaration

    Swift

    func requestStateForRegion(_ region: CLRegion!)

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    @NSCopying var rangedRegions: NSSet! { get }

    Objective-C

    @property(readonly, nonatomic, copy) NSSet *rangedRegions

    Discussion

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • Starts the generation of visit-related events.

    Declaration

    Swift

    func startMonitoringVisits()

    Objective-C

    - (void)startMonitoringVisits

    Discussion

    Calling this method begins the delivery of visit-related events to your app. Enabling visit events for one location manager enables visit events for all other location manager objects in your app. When a new visit event arrives, the location manager object delivers the event to the locationManager:didVisit: method of its delegate.

    If your app is terminated while this service is active, the system relaunches your app when new visit events are ready to be delivered. Upon relaunch, recreate your location manager object and assign a delegate to begin receiving visit events. You do not need to call this method again to restart the delivery of visit events but calling it does no harm.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 8.0 and later.

  • Stops the delivery of visit-related events.

    Declaration

    Swift

    func stopMonitoringVisits()

    Objective-C

    - (void)stopMonitoringVisits

    Discussion

    Calling this method disables the delivery of visit-related events for your app.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    func allowDeferredLocationUpdatesUntilTraveled(_ distance: CLLocationDistance, timeout timeout: NSTimeInterval)

    Objective-C

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

    Deferred updates are delivered only when the system enters a low power state. Deferred updates do not occur during debugging because Xcode prevents your app from sleeping and thus prevents the system from entering that low power state.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

  • Cancels the deferral of location updates for this app.

    Declaration

    Swift

    func disallowDeferredLocationUpdates()

    Objective-C

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

  • location location Property

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

    Declaration

    Swift

    @NSCopying var location: CLLocation! { get }

    Objective-C

    @property(readonly, nonatomic, copy) 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 app is terminated, this property is updated with the most recent location data when your app 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 app.

    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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

  • heading heading Property

    The most recently reported heading. (read-only)

    Declaration

    Swift

    @NSCopying var heading: CLHeading! { get }

    Objective-C

    @property(readonly, nonatomic, copy) CLHeading *heading

    Discussion

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

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

  • A Boolean value indicating whether location services are enabled on the device. (read-only)

    Deprecation Statement

    Use the locationServicesEnabled class method instead.

    Declaration

    Objective-C

    @property(readonly, nonatomic) BOOL locationServicesEnabled

    Discussion

    In iOS, the user can enable or disable location services using the controls in Settings > Location Services. In OS X, the user can enable or disable location services from the Security & Privacy system preference.

    You should check this property before starting location updates to determine whether the user has location services enabled for the current device. If this property contains the value NOfalse and you start location updates anyway, the Core Location framework prompts the user with a confirmation alert asking whether location services should be reenabled.

    Special Considerations

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

    Import Statement

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 4.0.

  • headingAvailable headingAvailable (iOS 4.0) Property

    A Boolean value indicating whether the location manager is able to generate heading-related events. (read-only)

    Deprecation Statement

    Use the headingAvailable class method instead.

    Declaration

    Objective-C

    @property(readonly, nonatomic) BOOL headingAvailable

    Discussion

    Heading data may not be available on all iOS-based devices. You should check the value of this property before asking the location manager to deliver heading-related events.

    Import Statement

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 4.0.

  • Returns a Boolean value indicating whether region monitoring is supported on the current device.

    Deprecation Statement

    Use isMonitoringAvailableForClass: instead.

    Declaration

    Objective-C

    + (BOOL)regionMonitoringAvailable

    Return Value

    YEStrue if region monitoring is available; NOfalse if it is not.

    Discussion

    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 app or for all apps.

    Special Considerations

    This class is deprecated in iOS 7 and later but is still supported in OS X.

    Import Statement

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Returns a Boolean value indicating whether region monitoring is currently enabled.

    Deprecation Statement

    Use isMonitoringAvailableForClass: and authorizationStatus instead.

    Declaration

    Objective-C

    + (BOOL)regionMonitoringEnabled

    Return Value

    YEStrue if region monitoring is available and is currently enabled; NOfalse if it is unavailable or not enabled.

    Discussion

    In iOS, the user can enable or disable location services (including region monitoring) using the controls in Settings > Location Services.

    You should check the return value of this method before starting region monitoring updates to determine whether the user currently allows location services to be used at all. If this method returns NOfalse and you start region monitoring updates anyway, the Core Location framework prompts the user to confirm 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.

    Import Statement

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

  • Starts monitoring the specified region for boundary crossings.

    Deprecation Statement

    Use startMonitoringForRegion: instead.

    Declaration

    Objective-C

    - (void)startMonitoringForRegion:(CLRegion *)region desiredAccuracy:(CLLocationAccuracy)accuracy

    Parameters

    region

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

    accuracy

    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.

    Discussion

    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 app, 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 app and stored in the monitoredRegions property.

    If you begin monitoring a region and your app 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 app delegate contains the key UIApplicationLaunchOptionsLocationKey to indicate that your app 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.

    Import Statement

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

  • purpose purpose (iOS 6.0) Property

    An app-provided string that describes the reason for using location services.

    Deprecation Statement

    Set the purpose string using the NSLocationAlwaysUsageDescription or NSLocationWhenInUseUsageDescription key in the app’s Info.plist instead.

    Declaration

    Objective-C

    @property(copy, nonatomic) NSString *purpose

    Discussion

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

    Import Statement

    Availability

    Available in iOS 3.2 and later.

    Deprecated in iOS 6.0.

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

    Declaration

    Swift

    enum CLAuthorizationStatus : Int32 { case NotDetermined case Restricted case Denied case Authorized case AuthorizedWhenInUse }

    Objective-C

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

    Constants

    • NotDetermined

      kCLAuthorizationStatusNotDetermined

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

      Available in iOS 4.2 and later.

    • Restricted

      kCLAuthorizationStatusRestricted

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

      Available in iOS 4.2 and later.

    • Denied

      kCLAuthorizationStatusDenied

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

      Available in iOS 4.2 and later.

    • Authorized

      kCLAuthorizationStatusAuthorized

      This app is authorized to use location services.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • kCLAuthorizationStatusAuthorizedAlways

      kCLAuthorizationStatusAuthorizedAlways

      This app is authorized to start location services at any time. This authorization allows you to use all location services, including those for monitoring regions and significant location changes.

      Available in iOS 8.0 and later.

    • AuthorizedWhenInUse

      kCLAuthorizationStatusAuthorizedWhenInUse

      This app is authorized to start most location services while running in the foreground. This authorization does not allow you to use APIs that could launch your app in response to an event, such as region monitoring and the significant location change services.

      Available in iOS 8.0 and later.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 4.2 and later.

  • Constants for specifying maximum values during deferred updates.

    Declaration

    Swift

    let CLLocationDistanceMax: CLLocationDistance let CLTimeIntervalMax: NSTimeInterval

    Objective-C

    extern const CLLocationDistance CLLocationDistanceMax; extern const NSTimeInterval CLTimeIntervalMax;

    Constants

    • CLLocationDistanceMax

      CLLocationDistanceMax

      A value representing an unlimited distance.

      Available in iOS 6.0 and later.

    • CLTimeIntervalMax

      CLTimeIntervalMax

      A value representing an unlimited amount of time.

      Available in iOS 6.0 and later.

    Import Statement

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

    Declaration

    Swift

    enum CLActivityType : Int { case Other case AutomotiveNavigation case Fitness case OtherNavigation }

    Objective-C

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

    Constants

    • Other

      CLActivityTypeOther

      The location manager is being used for an unknown activity.

      Available in iOS 6.0 and later.

    • AutomotiveNavigation

      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.

    • Fitness

      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.

    • OtherNavigation

      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.

    Import Statement

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.