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.h
The 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.h
The 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.h
The 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.h
The 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.h
The 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.h
The 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.h
Returns 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.h
Returns 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.h
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
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.h
Initializes 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.h
Represents a latitude or longitude value specified in degrees.
typedef double CLLocationDegrees;
CLLocation.h
A structure that contains a geographical coordinate using the WGS 84 reference frame.
typedef struct { CLLocationDegrees latitude; CLLocationDegrees longitude; } CLLocationCoordinate2D;
latitude
The latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator.
longitude
The 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.h
Represents the accuracy of a coordinate value in meters.
typedef double CLLocationAccuracy;
CLLocation.h
Constant 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;
kCLLocationAccuracyBestForNavigation
Use 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
.
kCLLocationAccuracyBest
Use the highest-level of accuracy.
Available in iOS 2.0 and later.
Declared in CLLocation.h
.
kCLLocationAccuracyNearestTenMeters
Accurate to within ten meters of the desired target.
Available in iOS 2.0 and later.
Declared in CLLocation.h
.
kCLLocationAccuracyHundredMeters
Accurate to within one hundred meters.
Available in iOS 2.0 and later.
Declared in CLLocation.h
.
kCLLocationAccuracyKilometer
Accurate to the nearest kilometer.
Available in iOS 2.0 and later.
Declared in CLLocation.h
.
kCLLocationAccuracyThreeKilometers
Accurate 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.h
Represents 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.h
Use this constant whenever you want to indicate that a coordinate is invalid.
const CLLocationCoordinate2D kCLLocationCoordinate2DInvalid
Last updated: 2010-05-11