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 |
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
-
– initWithLatitude:longitude: -
– initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:timestamp: -
– initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:course:speed:timestamp:
Location Attributes
-
coordinateproperty -
altitudeproperty -
horizontalAccuracyproperty -
verticalAccuracyproperty -
timestampproperty -
– description
Measuring the Distance Between Coordinates
-
– distanceFromLocation: -
– getDistanceFrom:Deprecated in iOS 3.2
Getting Speed and Course Information
Properties
altitude
The altitude measured in meters. (read-only)
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.
See Also
Declared In
CLLocation.hcoordinate
The geographical coordinate information. (read-only)
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.hcourse
The direction in which the device is traveling.
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.
Declared In
CLLocation.hhorizontalAccuracy
The radius of uncertainty for the location, measured in meters. (read-only)
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.
Declared In
CLLocation.hspeed
The instantaneous speed of the device in meters per second.
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.
Declared In
CLLocation.htimestamp
The time at which this location was determined. (read-only)
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.hverticalAccuracy
The accuracy of the altitude value in meters. (read-only)
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
Declared In
CLLocation.hInstance Methods
description
Returns the location data in a formatted text string.
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.hdistanceFromLocation:
Returns the distance (in meters) from the receiver’s location to the specified 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.
Declared In
CLLocation.hinitWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:course:speed:timestamp:
Initializes and returns a location object with the specified coordinate and course information.
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.hinitWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:timestamp:
Initializes and returns a location object with the specified coordinate information.
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.hinitWithLatitude:longitude:
Initializes and returns a location object with the specified latitude and 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© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-10-12)