| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreLocation.framework |
| Availability | Available in iOS 2.0 and later. |
| Declared in | CLLocation.h |
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.
– initWithLatitude:longitude:
– initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:timestamp:
coordinate property
altitude property
horizontalAccuracy property
verticalAccuracy property
timestamp property
– description
– distanceFromLocation:
– getDistanceFrom: Deprecated in iOS 3.2
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
The altitude measured in meters. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationDistance altitude
Positive values indicate altitudes above sea level. Negative values indicate altitudes below sea level.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocation.hThe geographical coordinate information. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationCoordinate2D coordinate
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.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocation.hThe direction in which the device is traveling.
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationDirection course
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.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocation.hThe radius of uncertainty for the location, measured in meters. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationAccuracy horizontalAccuracy
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.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocation.hThe instantaneous speed of the device in meters per second.
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationSpeed speed
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.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocation.hThe time at which this location was determined. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) NSDate *timestamp
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocation.hThe accuracy of the altitude value in meters. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationAccuracy verticalAccuracy
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.
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocation.hReturns the location data in a formatted text string.
- (NSString *)description
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.
The returned string is intended for display purposes only.
CLLocation.hReturns the distance (in meters) from the receiver’s location to the specified location.
- (CLLocationDistance)distanceFromLocation:(const CLLocation *)location
The other location.
The distance (in meters) between the two locations.
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.
CLLocation.hInitializes 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
A coordinate structure containing the latitude and longitude values.
The altitude value for the location.
The accuracy of the coordinate value. Specifying a negative number indicates that the coordinate value is invalid.
The accuracy of the altitude value. Specifying a negative number indicates that the altitude value is invalid.
The time to associate with the location object. Typically, you would set this to the current time.
A location object initialized with the specified information.
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.
CLLocation.hInitializes and returns a location object with the specified latitude and longitude.
- (id)initWithLatitude:(CLLocationDegrees)latitude longitude:(CLLocationDegrees)longitude
The latitude of the coordinate point.
The longitude of the coordinate point.
A location object initialized with the specified coordinate point.
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.
CLLocation.hRepresents a latitude or longitude value specified in degrees.
typedef double CLLocationDegrees;
CLLocation.hA structure that contains a geographical coordinate using the WGS 84 reference frame.
typedef struct {
CLLocationDegrees latitude;
CLLocationDegrees longitude;
} CLLocationCoordinate2D;
latitudeThe latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator.
longitudeThe longitude in degrees. Measurements are relative to the zero meridian, with positive values extending east of the meridian and negative values extending west of the meridian.
CLLocation.hRepresents the accuracy of a coordinate value in meters.
typedef double CLLocationAccuracy;
CLLocation.hConstant values you can use to specify the accuracy of a location.
extern const CLLocationAccuracy kCLLocationAccuracyBestForNavigation; extern const CLLocationAccuracy kCLLocationAccuracyBest; extern const CLLocationAccuracy kCLLocationAccuracyNearestTenMeters; extern const CLLocationAccuracy kCLLocationAccuracyHundredMeters; extern const CLLocationAccuracy kCLLocationAccuracyKilometer; extern const CLLocationAccuracy kCLLocationAccuracyThreeKilometers;
kCLLocationAccuracyBestForNavigationUse the highest possible accuracy and combine it with additional sensor data. This level of accuracy is intended for use in navigation applications that require precise position information at all times and are intended to be used only while the device is plugged in.
Available in iOS 4.0 and later.
Declared in CLLocation.h.
kCLLocationAccuracyBestUse the highest-level of accuracy.
Available in iOS 2.0 and later.
Declared in CLLocation.h.
kCLLocationAccuracyNearestTenMetersAccurate to within ten meters of the desired target.
Available in iOS 2.0 and later.
Declared in CLLocation.h.
kCLLocationAccuracyHundredMetersAccurate to within one hundred meters.
Available in iOS 2.0 and later.
Declared in CLLocation.h.
kCLLocationAccuracyKilometerAccurate to the nearest kilometer.
Available in iOS 2.0 and later.
Declared in CLLocation.h.
kCLLocationAccuracyThreeKilometersAccurate to the nearest three kilometers.
Available in iOS 2.0 and later.
Declared in CLLocation.h.
Represents the speed at which the device is moving in meters per second.
typedef double CLLocationSpeed;
CLLocation.hRepresents a direction that is measured in degrees relative to true north.
typedef double CLLocationDirection;
Direction values are measured in degrees starting at due north and continue clockwise around the compass. Thus, north is 0 degrees, east is 90 degrees, south is 180 degrees, and so on. A negative value indicates an invalid direction.
CLLocation.hUse this constant whenever you want to indicate that a coordinate is invalid.
const CLLocationCoordinate2D kCLLocationCoordinate2DInvalid
Last updated: 2010-05-11