CLLocation 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
Related sample code

Overview

A CLLocation object represents the location data generated by a CLLocationManager object. This object incorporates the geographical coordinates and altitude of the device’s location along with values indicating the accuracy of the measurements and when those measurements were made. In iOS, this class also reports information about the speed and heading in which the device is moving.

Typically, you use a CLLocationManager object to create instances of this class based on the last known location of the user’s device. You can create instances yourself, however, if you want to cache custom location data or get the distance between two points.

This class is designed to be used as is and should not be subclassed.

Tasks

Initializing a Location Object

Location Attributes

Measuring the Distance Between Coordinates

Getting Speed and Course Information

Properties

altitude

The altitude measured in meters. (read-only)

@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationDistance altitude
Discussion

Positive values indicate altitudes above sea level. Negative values indicate altitudes below sea level.

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
CLLocation.h

coordinate

The geographical coordinate information. (read-only)

@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationCoordinate2D coordinate
Discussion

When running in the simulator, Core Location assigns a fixed set of coordinate values to this property. You must run your application on an iOS-based device to get real location values.

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
CLLocation.h

course

The direction in which the device is traveling.

@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationDirection course
Discussion

Course values are measured in degrees starting at due north and continuing clockwise around the compass. Thus, north is 0 degrees, east is 90 degrees, south is 180 degrees, and so on. Course values may not be available on all devices. A negative value indicates that the direction is invalid.

Special Considerations

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

Availability
  • Available in iOS 2.2 and later.
Related Sample Code
Declared In
CLLocation.h

horizontalAccuracy

The radius of uncertainty for the location, measured in meters. (read-only)

@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationAccuracy horizontalAccuracy
Discussion

The location’s latitude and longitude identify the center of the circle, and this value indicates the radius of that circle. A negative value indicates that the location’s latitude and longitude are invalid.

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
CLLocation.h

speed

The instantaneous speed of the device in meters per second.

@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationSpeed speed
Discussion

This value reflects the instantaneous speed of the device in the direction of its current heading. A negative value indicates an invalid speed. Because the actual speed can change many times between the delivery of subsequent location events, you should use this property for informational purposes only.

Special Considerations

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

Availability
  • Available in iOS 2.2 and later.
Related Sample Code
Declared In
CLLocation.h

timestamp

The time at which this location was determined. (read-only)

@property(readonly, NS_NONATOMIC_IPHONEONLY) NSDate *timestamp
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
CLLocation.h

verticalAccuracy

The accuracy of the altitude value in meters. (read-only)

@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationAccuracy verticalAccuracy
Discussion

The value in the altitude property could be plus or minus the value indicated by this property. A negative value indicates that the altitude value is invalid.

Determining the vertical accuracy requires a device with GPS capabilities. Thus, on some earlier iOS-based devices, this property always contains a negative value.

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.
See Also
Related Sample Code
Declared In
CLLocation.h

Instance Methods

description

Returns the location data in a formatted text string.

- (NSString *)description
Return Value

A string of the form “<<latitude>, <longitude>> +/- <accuracy>m (speed <speed> kph / heading <heading>) @ <date-time>”, where <latitude>, <longitude>, <accuracy>, <speed>, and <heading> are formatted floating point numbers and <date-time> is a formatted date string that includes date, time, and time zone information.

Discussion

The returned string is intended for display purposes only.

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

distanceFromLocation:

Returns the distance (in meters) from the receiver’s location to the specified location.

- (CLLocationDistance)distanceFromLocation:(const CLLocation *)location
Parameters
location

The other location.

Return Value

The distance (in meters) between the two locations.

Discussion

This method measures the distance between the two locations by tracing a line between them that follows the curvature of the Earth. The resulting arc is a smooth curve and does not take into account specific altitude changes between the two locations.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
CLLocation.h

initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:course:speed:timestamp:

Initializes and returns a location object with the specified coordinate and course information.

- (id)initWithCoordinate:(CLLocationCoordinate2D)coordinate altitude:(CLLocationDistance)altitude horizontalAccuracy:(CLLocationAccuracy)hAccuracy verticalAccuracy:(CLLocationAccuracy)vAccuracy course:(CLLocationDirection)course speed:(CLLocationSpeed)speed timestamp:(NSDate *)timestamp
Parameters
coordinate

A coordinate structure containing the latitude and longitude values.

altitude

The altitude value for the location.

hAccuracy

The accuracy of the coordinate value. Specifying a negative number indicates that the coordinate value is invalid.

vAccuracy

The accuracy of the altitude value. Specifying a negative number indicates that the altitude value is invalid.

course

The direction of travel for the location.

speed

The current speed associated with this location.

timestamp

The time to associate with the location object. Typically, you would set this to the current time.

Return Value

A location object initialized with the specified information.

Discussion

Typically, you acquire location objects from the location service, but you can use this method to create new location objects for other uses in your application.

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

initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:timestamp:

Initializes and returns a location object with the specified coordinate information.

- (id)initWithCoordinate:(CLLocationCoordinate2D)coordinate altitude:(CLLocationDistance)altitude horizontalAccuracy:(CLLocationAccuracy)hAccuracy verticalAccuracy:(CLLocationAccuracy)vAccuracy timestamp:(NSDate *)timestamp
Parameters
coordinate

A coordinate structure containing the latitude and longitude values.

altitude

The altitude value for the location.

hAccuracy

The accuracy of the coordinate value. Specifying a negative number indicates that the coordinate value is invalid.

vAccuracy

The accuracy of the altitude value. Specifying a negative number indicates that the altitude value is invalid.

timestamp

The time to associate with the location object. Typically, you would set this to the current time.

Return Value

A location object initialized with the specified information.

Discussion

Typically, you acquire location objects from the location service, but you can use this method to create new location objects for other uses in your application.

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

initWithLatitude:longitude:

Initializes and returns a location object with the specified latitude and longitude.

- (id)initWithLatitude:(CLLocationDegrees)latitude longitude:(CLLocationDegrees)longitude
Parameters
latitude

The latitude of the coordinate point.

longitude

The longitude of the coordinate point.

Return Value

A location object initialized with the specified coordinate point.

Discussion

Typically, you acquire location objects from the location service, but you can use this method to create new location objects for other uses in your application. When using this method, the other properties of the object are initialized to appropriate values. In particular, the altitude and horizontalAccuracy properties are set to 0, the verticalAccuracy property is set to -1 to indicate that the altitude value is invalid, and the timestamp property is set to the time at which the instance was initialized.

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