iOS Developer Library

Developer

CoreLocation Framework Reference CLLocation Class Reference

Options
Deployment Target:

On This Page
Language:

CLLocation

Inheritance


Import Statement


Swift

import CoreLocation

Objective-C

@import CoreLocation;

Availability


Available in iOS 2.0 and later.

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.

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

    Declaration

    Swift

    init!(latitude latitude: CLLocationDegrees, longitude longitude: CLLocationDegrees)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init!(coordinate coordinate: CLLocationCoordinate2D, altitude altitude: CLLocationDistance, horizontalAccuracy hAccuracy: CLLocationAccuracy, verticalAccuracy vAccuracy: CLLocationAccuracy, timestamp timestamp: NSDate!)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init!(coordinate coordinate: CLLocationCoordinate2D, altitude altitude: CLLocationDistance, horizontalAccuracy hAccuracy: CLLocationAccuracy, verticalAccuracy vAccuracy: CLLocationAccuracy, course course: CLLocationDirection, speed speed: CLLocationSpeed, timestamp timestamp: NSDate!)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 4.2 and later.

  • The geographical coordinate information. (read-only)

    Declaration

    Swift

    var coordinate: CLLocationCoordinate2D { get }

    Objective-C

    @property(readonly, nonatomic) CLLocationCoordinate2D coordinate

    Discussion

    When running in the simulator, Core Location uses the values provided to it by the simulator. You must run your application on an iOS-based device to get the actual location of that device.

    Special Considerations

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

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

  • altitude altitude Property

    The altitude measured in meters. (read-only)

    Declaration

    Swift

    var altitude: CLLocationDistance { get }

    Objective-C

    @property(readonly, nonatomic) 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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

    See Also

    verticalAccuracy

  • floor floor Property

    The logical floor of the building in which the user is located. (read-only)

    Declaration

    Swift

    @NSCopying var floor: CLFloor! { get }

    Objective-C

    @property(readonly, nonatomic, copy) CLFloor *floor

    Discussion

    If floor information is not available for the current location, the value of this property is nil.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var horizontalAccuracy: CLLocationAccuracy { get }

    Objective-C

    @property(readonly, nonatomic) 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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var verticalAccuracy: CLLocationAccuracy { get }

    Objective-C

    @property(readonly, nonatomic) 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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

    See Also

    altitude

  • timestamp timestamp Property

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

    Declaration

    Swift

    @NSCopying var timestamp: NSDate! { get }

    Objective-C

    @property(readonly, nonatomic, copy) NSDate *timestamp

    Special Considerations

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

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

  • The location data in a formatted text string. (read-only)

    Declaration

    Swift

    var description: String! { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSString *description

    Discussion

    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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func distanceFromLocation(_ location: CLLocation!) -> CLLocationDistance

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 3.2 and later.

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

    Deprecation Statement

    Use the distanceFromLocation: method instead.

    Declaration

    Objective-C

    - (CLLocationDistance)getDistanceFrom:(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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 3.2.

  • speed speed Property

    The instantaneous speed of the device in meters per second.

    Declaration

    Swift

    var speed: CLLocationSpeed { get }

    Objective-C

    @property(readonly, nonatomic) 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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.2 and later.

  • course course Property

    The direction in which the device is traveling.

    Declaration

    Swift

    var course: CLLocationDirection { get }

    Objective-C

    @property(readonly, nonatomic) 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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.2 and later.