Core Location

Obtain the geographic location and orientation of a device.


Core Location provides services that determine a device’s geographic location, altitude, and orientation, or its position relative to a nearby iBeacon device. The framework gathers data using all available components on the device, including the Wi-Fi, GPS, Bluetooth, magnetometer, barometer, and cellular hardware.

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

  • Standard and significant location updates. Track large or small changes in the user’s current location with a configurable degree of accuracy.

  • Region monitoring. Monitor distinct regions of interest and generate location events when the user enters or leaves those regions.

  • Beacon ranging. Detect and locate nearby beacons.

  • Compass headings. Report heading changes from the onboard compass.

To use location services, your app requests authorization and the system prompts the user to grant or deny the request. An initial prompt is shown in Figure 1.

A screenshot of an iPhone showing a prompt asking the user if they allow the "Find My" app to have access to their location. The options are "Allow While Using App", "Allow Once", and "Don't Allow".

On iOS devices, users can change location service settings at any time in the Settings app, affecting individual apps or the device as a whole. Your app receives events, including authorization changes, in your location manager's delegate object, which conforms to the CLLocationManagerDelegate protocol.



Adding Location Services to Your App

Implement features that can access information about a user’s location.

class CLLocationManager

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

protocol CLLocationManagerDelegate

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


Choosing the Location Services Authorization to Request

Determine the authorization your app needs to access location data.

Requesting Authorization for Location Services

Ask the user for permission to access their location.

Responding to Changes in Authorization Status

Receive and respond to changes in your app's authorization status in your delegate's method.

enum CLAuthorizationStatus

Constants indicating the app's authorization to use location services.

property list key NSLocationAlwaysAndWhenInUseUsageDescription

A message that tells the user why the app is requesting access to the user’s location information at all times.

Name: Privacy - Location Always and When In Use Usage Description
property list key NSLocationWhenInUseUsageDescription

A message that tells the user why the app is requesting access to the user’s location information while the app is running in the foreground.

Name: Privacy - Location When In Use Usage Description
property list key NSLocationUsageDescription

A message that tells the user why the app is requesting access to the user’s location information.

Name: Privacy - Location Usage Description
property list key NSLocationAlwaysUsageDescription

A message that tells the user why the app is requesting access to the user's location at all times.

Name: Privacy - Location Always Usage Description

Location Updates

Getting the User's Location

Receive location data in your app.

class CLLocation

The latitude, longitude, and course information reported by the system.

struct CLLocationCoordinate2D

The latitude and longitude associated with a location, specified using the WGS 84 reference frame.

class CLFloor

The floor of a building on which the user's device is located.

class CLVisit

Information about the user's location during a specific period of time.

Region Monitoring

Configure geofences and receive notifications when the user's device crosses the fence's boundaries.

Monitoring the User's Proximity to Geographic Regions

Use region monitoring to determine when the user enters or leaves a geographic region.

class CLCircularRegion

A circular geographic region, specified as a center point and radius.

class CLRegion

A base class representing an area that can be monitored.


Ranging for Beacons

Configure a device to act as a beacon and to detect surrounding beacons.

Determining the Proximity to an iBeacon Device

Detect beacons and determine the relative distance to them.

Turning an iOS Device into an iBeacon Device

Broadcast iBeacon signals from an iOS device.

class CLBeacon

Information about an observed iBeacon device and its relative distance to the user’s device.

class CLBeaconRegion

A region used to detect the presence of iBeacon devices.

class CLBeaconIdentityConstraint

Identity characteristics that can match one or more beacons.

Compass Headings

Determine the device’s orientation relative to magnetic or true north.

Getting Heading and Course Information

Use a device’s orientation and course information for navigation.

class CLHeading

The azimuth (orientation) of the user’s device, relative to true or magnetic north.


Converting Between Coordinates and User-Friendly Place Names

Convert between a latitude/longitude pair and a more user-friendly description of that location.

class CLGeocoder

An interface for converting between geographic coordinates and place names.

class CLPlacemark

A user-friendly description of a geographic coordinate, often containing the name of the place, its address, and other relevant information.


struct CLError

A Core Location error.

enum CLError.Code

Error codes returned by the location manager object.

let kCLErrorUserInfoAlternateRegionKey: String

A key in the user information dictionary of an error relating to a delayed region monitoring response.

let kCLErrorDomain: String

The domain for Core Location errors.

See Also