CLLocation Class ReferenceData Management: Device Information
2010-10-12
Apple Inc.© 2010 Apple Inc.All rights reserved.
No part of this publication may be reproduced,stored in a retrieval system, or transmitted, inany form or by any means, mechanical,electronic, photocopying, recording, orotherwise, without prior written permission ofApple Inc., with the following exceptions: Anyperson is hereby authorized to storedocumentation on a single computer forpersonal use only and to print copies ofdocumentation for personal use provided thatthe documentation contains Apple’s copyrightnotice.
The Apple logo is a trademark of Apple Inc.
No licenses, express or implied, are grantedwith respect to any of the technology describedin this document. Apple retains all intellectualproperty rights associated with the technologydescribed in this document. This document isintended to assist application developers todevelop applications only for Apple-labeledcomputers.
Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010
Apple, the Apple logo, Mac, Mac OS, andObjective-C are trademarks of Apple Inc.,registered in the United States and othercountries.
IOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.
Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TOTHIS DOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT ISPROVIDED “AS IS,” AND YOU, THE READER, AREASSUMING THE ENTIRE RISK AS TO ITS QUALITYAND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIAL DAMAGES RESULTING FROM ANYDEFECT OR INACCURACY IN THIS DOCUMENT, evenif advised of the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Appledealer, agent, or employee is authorized to makeany modification, extension, or addition to thiswarranty.
Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation or
exclusion may not apply to you. This warranty givesyou specific legal rights, and you may also haveother rights which vary from state to state.
Contents
CLLocation Class Reference 5
Overview 5Tasks 6
Initializing a Location Object 6Location Attributes 6Measuring the Distance Between Coordinates 6Getting Speed and Course Information 7
Properties 7altitude 7coordinate 7course 8horizontalAccuracy 8speed 9timestamp 9verticalAccuracy 9
Instance Methods 10description 10distanceFromLocation: 10initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:course:speed: timestamp: 11initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:timestamp: 12initWithLatitude:longitude: 12
Appendix A Deprecated CLLocation Methods 15
Deprecated in iOS 3.2 15getDistanceFrom: 15
Document Revision History 17
32010-10-12 | © 2010 Apple Inc. All Rights Reserved.
42010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CONTENTS
Inherits from NSObject
Conforms to NSCodingNSCopyingNSObject (NSObject)
Framework /System/Library/Frameworks/CoreLocation.framework
Availability Available in iOS 2.0 and later.
Companion guide Location Awareness Programming Guide
Declared in CLLocation.h
Related sample code LocateMeLocationsPhotoLocationsTaggedLocations
Overview
A CLLocation object represents the location data generated by a CLLocationManager object. This objectincorporates the geographical coordinates and altitude of the device’s location along with values indicatingthe accuracy of the measurements and when those measurements were made. In iOS, this class also reportsinformation 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 knownlocation of the user’s device. You can create instances yourself, however, if you want to cache custom locationdata or get the distance between two points.
This class is designed to be used as is and should not be subclassed.
Overview 52010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
Tasks
Initializing a Location Object
– initWithLatitude:longitude: (page 12)Initializes and returns a location object with the specified latitude and longitude.
– initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:timestamp: (page12)
Initializes and returns a location object with the specified coordinate information.
– initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:course:speed:timestamp: (page11)
Initializes and returns a location object with the specified coordinate and course information.
Location Attributes
coordinate (page 7) propertyThe geographical coordinate information. (read-only)
altitude (page 7) propertyThe altitude measured in meters. (read-only)
horizontalAccuracy (page 8) propertyThe radius of uncertainty for the location, measured in meters. (read-only)
verticalAccuracy (page 9) propertyThe accuracy of the altitude value in meters. (read-only)
timestamp (page 9) propertyThe time at which this location was determined. (read-only)
– description (page 10)Returns the location data in a formatted text string.
Measuring the Distance Between Coordinates
– distanceFromLocation: (page 10)Returns the distance (in meters) from the receiver’s location to the specified location.
– getDistanceFrom: (page 15) Deprecated in iOS 3.2Returns the distance (in meters) from the receiver’s location to the specified location. (Deprecated.Use the distanceFromLocation: (page 10) method instead.)
6 Tasks2010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
Getting Speed and Course Information
speed (page 9) propertyThe instantaneous speed of the device in meters per second.
course (page 8) propertyThe direction in which the device is traveling.
Properties
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
altitudeThe altitude measured in meters. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationDistance altitude
DiscussionPositive values indicate altitudes above sea level. Negative values indicate altitudes below sea level.
Special Considerations
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
AvailabilityAvailable in iOS 2.0 and later.
See Also @property verticalAccuracy (page 9)
Declared InCLLocation.h
coordinateThe geographical coordinate information. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationCoordinate2D coordinate
DiscussionWhen running in the simulator, Core Location assigns a fixed set of coordinate values to this property. Youmust run your application on an iOS-based device to get real location values.
Special Considerations
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
Properties 72010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
AvailabilityAvailable in iOS 2.0 and later.
Related Sample CodeLocationsPhotoLocationsTaggedLocations
Declared InCLLocation.h
courseThe direction in which the device is traveling.
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationDirection course
DiscussionCourse 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 beavailable on all devices. A negative value indicates that the direction is invalid.
Special Considerations
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
AvailabilityAvailable in iOS 2.2 and later.
Related Sample CodeLocateMe
Declared InCLLocation.h
horizontalAccuracyThe radius of uncertainty for the location, measured in meters. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationAccuracy horizontalAccuracy
DiscussionThe location’s latitude and longitude identify the center of the circle, and this value indicates the radius ofthat 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 Mac OS X, it is declared as atomic.
AvailabilityAvailable in iOS 2.0 and later.
Related Sample CodeLocateMe
8 Properties2010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
Declared InCLLocation.h
speedThe instantaneous speed of the device in meters per second.
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationSpeed speed
DiscussionThis value reflects the instantaneous speed of the device in the direction of its current heading. A negativevalue indicates an invalid speed. Because the actual speed can change many times between the delivery ofsubsequent location events, you should use this property for informational purposes only.
Special Considerations
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
AvailabilityAvailable in iOS 2.2 and later.
Related Sample CodeLocateMe
Declared InCLLocation.h
timestampThe 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 Mac OS X, it is declared as atomic.
AvailabilityAvailable in iOS 2.0 and later.
Declared InCLLocation.h
verticalAccuracyThe accuracy of the altitude value in meters. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocationAccuracy verticalAccuracy
DiscussionThe value in the altitude property could be plus or minus the value indicated by this property. A negativevalue indicates that the altitude value is invalid.
Properties 92010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
Determining the vertical accuracy requires a device with GPS capabilities. Thus, on some earlier iOS-baseddevices, this property always contains a negative value.
Special Considerations
In iOS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
AvailabilityAvailable in iOS 2.0 and later.
See Also @property altitude (page 7)
Related Sample CodeLocateMe
Declared InCLLocation.h
Instance Methods
descriptionReturns the location data in a formatted text string.
- (NSString *)description
Return ValueA string of the form “<<latitude>, <longitude>> +/- <accuracy>m (speed <speed> kph / heading <heading>)@ <date-time>”, where <latitude>, <longitude>, <accuracy>, <speed>, and <heading> are formatted floatingpoint numbers and <date-time> is a formatted date string that includes date, time, and time zone information.
DiscussionThe returned string is intended for display purposes only.
AvailabilityAvailable in iOS 2.0 and later.
Declared InCLLocation.h
distanceFromLocation:Returns the distance (in meters) from the receiver’s location to the specified location.
- (CLLocationDistance)distanceFromLocation:(const CLLocation *)location
Parameterslocation
The other location.
10 Instance Methods2010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
Return ValueThe distance (in meters) between the two locations.
DiscussionThis method measures the distance between the two locations by tracing a line between them that followsthe curvature of the Earth. The resulting arc is a smooth curve and does not take into account specific altitudechanges between the two locations.
AvailabilityAvailable in iOS 3.2 and later.
Declared InCLLocation.h
initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:course:speed:timestamp:Initializes and returns a location object with the specified coordinate and course information.
- (id)initWithCoordinate:(CLLocationCoordinate2D)coordinatealtitude:(CLLocationDistance)altitudehorizontalAccuracy:(CLLocationAccuracy)hAccuracyverticalAccuracy:(CLLocationAccuracy)vAccuracy course:(CLLocationDirection)coursespeed:(CLLocationSpeed)speed timestamp:(NSDate *)timestamp
Parameterscoordinate
A coordinate structure containing the latitude and longitude values.
altitudeThe altitude value for the location.
hAccuracyThe accuracy of the coordinate value. Specifying a negative number indicates that the coordinatevalue is invalid.
vAccuracyThe accuracy of the altitude value. Specifying a negative number indicates that the altitude value isinvalid.
courseThe direction of travel for the location.
speedThe current speed associated with this location.
timestampThe time to associate with the location object. Typically, you would set this to the current time.
Return ValueA location object initialized with the specified information.
DiscussionTypically, you acquire location objects from the location service, but you can use this method to create newlocation objects for other uses in your application.
AvailabilityAvailable in iOS 4.2 and later.
Instance Methods 112010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
Declared InCLLocation.h
initWithCoordinate:altitude:horizontalAccuracy:verticalAccuracy:timestamp:Initializes and returns a location object with the specified coordinate information.
- (id)initWithCoordinate:(CLLocationCoordinate2D)coordinatealtitude:(CLLocationDistance)altitudehorizontalAccuracy:(CLLocationAccuracy)hAccuracyverticalAccuracy:(CLLocationAccuracy)vAccuracy timestamp:(NSDate *)timestamp
Parameterscoordinate
A coordinate structure containing the latitude and longitude values.
altitudeThe altitude value for the location.
hAccuracyThe accuracy of the coordinate value. Specifying a negative number indicates that the coordinatevalue is invalid.
vAccuracyThe accuracy of the altitude value. Specifying a negative number indicates that the altitude value isinvalid.
timestampThe time to associate with the location object. Typically, you would set this to the current time.
Return ValueA location object initialized with the specified information.
DiscussionTypically, you acquire location objects from the location service, but you can use this method to create newlocation objects for other uses in your application.
AvailabilityAvailable in iOS 2.0 and later.
Declared InCLLocation.h
initWithLatitude:longitude:Initializes and returns a location object with the specified latitude and longitude.
- (id)initWithLatitude:(CLLocationDegrees)latitudelongitude:(CLLocationDegrees)longitude
Parameterslatitude
The latitude of the coordinate point.
longitudeThe longitude of the coordinate point.
12 Instance Methods2010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
Return ValueA location object initialized with the specified coordinate point.
DiscussionTypically, you acquire location objects from the location service, but you can use this method to create newlocation objects for other uses in your application. When using this method, the other properties of the objectare initialized to appropriate values. In particular, the altitude and horizontalAccuracy properties areset to 0, the verticalAccuracy property is set to -1 to indicate that the altitude value is invalid, and thetimestamp property is set to the time at which the instance was initialized.
AvailabilityAvailable in iOS 2.0 and later.
Declared InCLLocation.h
Instance Methods 132010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
14 Instance Methods2010-10-12 | © 2010 Apple Inc. All Rights Reserved.
CLLocation Class Reference
A method identified as deprecated has been superseded and may become unsupported in the future.
Deprecated in iOS 3.2
getDistanceFrom:Returns the distance (in meters) from the receiver’s location to the specified location. (Deprecated in iOS 3.2.Use the distanceFromLocation: (page 10) method instead.)
- (CLLocationDistance)getDistanceFrom:(const CLLocation *)location
Parameterslocation
The other location.
Return ValueThe distance (in meters) between the two locations.
DiscussionThis method measures the distance between the two locations by tracing a line between them that followsthe curvature of the Earth. The resulting arc is a smooth curve and does not take into account specific altitudechanges between the two locations.
AvailabilityAvailable in iOS 2.0 and later.Deprecated in iOS 3.2.
Declared InCLLocation.h
Deprecated in iOS 3.2 152010-10-12 | © 2010 Apple Inc. All Rights Reserved.
APPENDIX A
Deprecated CLLocation Methods
16 Deprecated in iOS 3.22010-10-12 | © 2010 Apple Inc. All Rights Reserved.
APPENDIX A
Deprecated CLLocation Methods
This table describes the changes to CLLocation Class Reference.
NotesDate
Moved the types and constants to the new Core Location Data Types Referenceand Core Location Constants Reference documents.
2010-10-12
Updated to include symbols introduced in iOS 4.0.2010-05-11
Updated for iOS 3.2.2010-02-25
Updated the document to reflect the availability of the interfaces in Mac OS Xv10.6.
2009-08-04
Documented units for the speed property.2009-02-06
Documented new properties in iOS v2.2.2008-10-23
New document that describes the class for representing the geographicalcoordinates and altitude of a device's location, and related values.
2008-05-27
172010-10-12 | © 2010 Apple Inc. All Rights Reserved.
REVISION HISTORY
Document Revision History
182010-10-12 | © 2010 Apple Inc. All Rights Reserved.
REVISION HISTORY
Document Revision History