CLLocation Class

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.


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.


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.



Properties 72010-10-12 | © 2010 Apple Inc. All Rights Reserved.



Related Sample CodeLocationsPhotoLocationsTaggedLocations


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.




Related Sample CodeLocateMe


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.





8 Properties2010-10-12 | © 2010 Apple Inc. All Rights Reserved.



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.






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

@property(readonly, NS_NONATOMIC_IPHONEONLY) NSDate *timestamp





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.


Determining the vertical accuracy requires a device with GPS capabilities. Thus, on some earlier iOS-baseddevices, this property always contains a negative value.




See Also @property altitude (page 7)



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.



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.


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.



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.


Instance Methods 112010-10-12 | © 2010 Apple Inc. All Rights Reserved.



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.



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.



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.



Instance Methods 132010-10-12 | © 2010 Apple Inc. All Rights Reserved.




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.


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


REVISION HISTORY

Document Revision History


REVISION HISTORY

Document Revision History

Documents

CLLocation Class