Class

CLLocationManager

The object that you use to start and stop the delivery of location-related events to your app.

Overview

You use instances of this class to configure, start, and stop the Core Location services. A location manager object supports the following location-related activities:

  • Tracking large or small changes in the user’s current location with a configurable degree of accuracy.

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

  • Deferring the delivery of location updates while the app is in the background. (iOS only)

  • Reporting the range to nearby beacons.

When you are ready to use location services, follow these steps:

  1. Check to see if your app is authorized to use location services and request permission if your app's authorization status is not yet determined, as described in Requesting Permission to Use Location Services.

  2. Check to see if the appropriate location services are available for you to use, as described in Determining the Availability of Location Services.

  3. Create an instance of the CLLocationManager class and store a strong reference to it somewhere in your app.

    Keeping a strong reference to the location manager object is required until all tasks involving that object are complete. Because most location manager tasks run asynchronously, storing your location manager in a local variable is insufficient.

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

  5. Configure the properties related to the service you intend to use. For example, when getting location updates, always configure the distanceFilter and desiredAccuracy properties.

  6. Call the appropriate method to start the delivery of events.

For the services you use, configure any properties associated with that service accurately. Core Location 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, which can lead to significant power savings.

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 you use to receive events, see CLLocationManagerDelegate.

Topics

Requesting Authorization for Location Services

func requestWhenInUseAuthorization()

Requests permission to use location services while the app is in the foreground.

func requestAlwaysAuthorization()

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

enum CLAuthorizationStatus

Constants indicating whether the app is authorized to use location services.

Determining the Availability of Services

class func authorizationStatus()

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

class func locationServicesEnabled()

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

class func deferredLocationUpdatesAvailable()

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

class func significantLocationChangeMonitoringAvailable()

Returns a Boolean value indicating whether the significant-change location service is available.

class func headingAvailable()

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

class func isMonitoringAvailable(for: AnyClass)

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

class func isRangingAvailable()

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

Receiving Data from Location Services

var delegate: CLLocationManagerDelegate?

The delegate object to receive update events.

protocol CLLocationManagerDelegate

The methods that you use to receive events from an associated location manager object.

Initiating Standard Location Updates

func startUpdatingLocation()

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

func stopUpdatingLocation()

Stops the generation of location updates.

func requestLocation()

Requests the one-time delivery of the user’s current location.

var pausesLocationUpdatesAutomatically: Bool

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

var allowsBackgroundLocationUpdates: Bool

A Boolean value indicating whether the app should receive location updates when suspended.

var distanceFilter: CLLocationDistance

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

var desiredAccuracy: CLLocationAccuracy

The accuracy of the location data.

var activityType: CLActivityType

The type of user activity associated with the location updates.

enum CLActivityType

Constants indicating the type of activity associated with location updates.

Initiating Significant Location Updates

func startMonitoringSignificantLocationChanges()

Starts the generation of updates based on significant location changes.

func stopMonitoringSignificantLocationChanges()

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

Initiating Heading Updates

func startUpdatingHeading()

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

func stopUpdatingHeading()

Stops the generation of heading updates.

func dismissHeadingCalibrationDisplay()

Dismisses the heading calibration view from the screen immediately.

var headingFilter: CLLocationDegrees

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

var headingOrientation: CLDeviceOrientation

The device orientation to use when computing heading values.

enum CLDeviceOrientation

Constants indicating the physical orientation of the device.

Initiating Region Monitoring

func startMonitoring(for: CLRegion)

Starts monitoring the specified region.

func stopMonitoring(for: CLRegion)

Stops monitoring the specified region.

var monitoredRegions: Set<CLRegion>

The set of shared regions monitored by all location manager objects.

var maximumRegionMonitoringDistance: CLLocationDistance

The largest boundary distance that can be assigned to a region.

Initiating Beacon Ranging Requests

func startRangingBeacons(in: CLBeaconRegion)

Starts the delivery of notifications for the specified beacon region.

func stopRangingBeacons(in: CLBeaconRegion)

Stops the delivery of notifications for the specified beacon region.

func requestState(for: CLRegion)

Retrieves the state of a region asynchronously.

var rangedRegions: Set<CLRegion>

The set of regions currently being tracked using ranging.

Initiating Visit Event Updates

func startMonitoringVisits()

Starts the delivery of visit-related events.

func stopMonitoringVisits()

Stops the delivery of visit-related events.

Deferring Location Updates

func allowDeferredLocationUpdates(untilTraveled: CLLocationDistance, timeout: TimeInterval)

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

func disallowDeferredLocationUpdates()

Cancels the deferral of location updates for this app.

Getting Recently Retrieved Data

var location: CLLocation?

The most recently retrieved user location.

var heading: CLHeading?

The most recently reported heading.

Related Types

typealias CLLocationDegrees

A latitude or longitude value specified in degrees.

typealias CLLocationDistance

A distance measurement (measured in meters) from an existing location.

Constants

let kCLDistanceFilterNone: CLLocationDistance

A constant indicating that all movement should be reported.

let kCLHeadingFilterNone: CLLocationDegrees

A constant indicating that all header values should be reported.

let CLLocationDistanceMax: CLLocationDistance

A constant indicating the maximum distance.

let CLTimeIntervalMax: TimeInterval

A value representing an unlimited amount of time.

Deprecated

var purpose: String?

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

class func regionMonitoringAvailable()

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

Deprecated
class func regionMonitoringEnabled()

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

Deprecated

Relationships

Inherits From

Conforms To

See Also

First Steps

Choosing the Authorization Level for Location Services

Choose the appropriate level of access to location data for your app.

Determining the Availability of Location Services

Determine which location services are active and available on the user's device.

protocol CLLocationManagerDelegate

The methods that you use to receive events from an associated location manager object.