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

requestWhenInUseAuthorization

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

requestAlwaysAuthorization

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

CLAuthorizationStatus

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

Determining the Availability of Services

authorizationStatus

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

locationServicesEnabled

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

deferredLocationUpdatesAvailable

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

significantLocationChangeMonitoringAvailable

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

headingAvailable

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

isMonitoringAvailableForClass:

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

isRangingAvailable

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

Receiving Data from Location Services

delegate

The delegate object to receive update events.

CLLocationManagerDelegate

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

Initiating Standard Location Updates

startUpdatingLocation

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

stopUpdatingLocation

Stops the generation of location updates.

requestLocation

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

pausesLocationUpdatesAutomatically

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

allowsBackgroundLocationUpdates

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

distanceFilter

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

desiredAccuracy

The accuracy of the location data.

activityType

The type of user activity associated with the location updates.

CLActivityType

Constants indicating the type of activity associated with location updates.

Initiating Significant Location Updates

startMonitoringSignificantLocationChanges

Starts the generation of updates based on significant location changes.

stopMonitoringSignificantLocationChanges

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

Initiating Heading Updates

startUpdatingHeading

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

stopUpdatingHeading

Stops the generation of heading updates.

dismissHeadingCalibrationDisplay

Dismisses the heading calibration view from the screen immediately.

headingFilter

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

headingOrientation

The device orientation to use when computing heading values.

CLDeviceOrientation

Constants indicating the physical orientation of the device.

Initiating Region Monitoring

startMonitoringForRegion:

Starts monitoring the specified region.

stopMonitoringForRegion:

Stops monitoring the specified region.

monitoredRegions

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

maximumRegionMonitoringDistance

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

Initiating Beacon Ranging Requests

startRangingBeaconsInRegion:

Starts the delivery of notifications for the specified beacon region.

stopRangingBeaconsInRegion:

Stops the delivery of notifications for the specified beacon region.

requestStateForRegion:

Retrieves the state of a region asynchronously.

rangedRegions

The set of regions currently being tracked using ranging.

Initiating Visit Event Updates

startMonitoringVisits

Starts the delivery of visit-related events.

stopMonitoringVisits

Stops the delivery of visit-related events.

Deferring Location Updates

allowDeferredLocationUpdatesUntilTraveled:timeout:

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

disallowDeferredLocationUpdates

Cancels the deferral of location updates for this app.

Getting Recently Retrieved Data

location

The most recently retrieved user location.

heading

The most recently reported heading.

Related Types

CLLocationDegrees

A latitude or longitude value specified in degrees.

CLLocationDistance

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

Constants

kCLDistanceFilterNone

A constant indicating that all movement should be reported.

kCLHeadingFilterNone

A constant indicating that all header values should be reported.

CLLocationDistanceMax

A constant indicating the maximum distance.

CLTimeIntervalMax

A value representing an unlimited amount of time.

Deprecated

locationServicesEnabled

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

Deprecated
headingAvailable

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

Deprecated
purpose

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

regionMonitoringAvailable

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

Deprecated
regionMonitoringEnabled

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

Deprecated
startMonitoringForRegion:desiredAccuracy:

Starts monitoring the specified region for boundary crossings.

Deprecated

Relationships

Inherits From

See Also

First Steps

Requesting Permission to Use Location Services

Obtain user permission to use location services in your app.

Determining the Availability of Location Services

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

CLLocationManagerDelegate

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