android.location
Class Location

java.lang.Object
  android.location.Location

All Implemented Interfaces:

Parcelable

public class Location
extends Object
implements Parcelable

A class representing a geographic location sensed at a particular time (a "fix"). A location consists of a latitude and longitude, a UTC timestamp. and optionally information on altitude, speed, and bearing.

Information specific to a particular provider or class of providers may be communicated to the application using getExtras, which returns a Bundle of key/value pairs. Each provider will only provide those entries for which information is available.

Nested Class Summary

Nested classes/interfaces inherited from interface android.os.Parcelable

Parcelable.Creator<T>

Field Summary

static Parcelable.Creator<Location>	CREATOR
static int	FORMAT_DEGREES Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD.DDDDD where D indicates degrees.
static int	FORMAT_MINUTES Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD:MM.MMMMM" where D indicates degrees and M indicates minutes of arc (1 minute = 1/60th of a degree).
static int	FORMAT_SECONDS Constant used to specify formatting of a latitude or longitude in the form "DDD:MM:SS.SSSSS" where D indicates degrees, M indicates minutes of arc, and S indicates seconds of arc (1 minute = 1/60th of a degree, 1 second = 1/3600th of a degree).

Fields inherited from interface android.os.Parcelable

CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE

Constructor Summary

Location(Location l)
Constructs a new Location object that is a copy of the given location.

Location(String provider)
Constructs a new Location.

Method Summary

float	bearingTo(Location dest) Returns the approximate initial bearing in degrees East of true North when traveling along the shortest path between this location and the given location.
static String	convert(double coordinate, int outputType) Converts a coordinate to a String representation.
static double	convert(String coordinate) Converts a String in one of the formats described by FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS into a double.
int	describeContents() Describe the kinds of special objects contained in this Parcelable's marshalled representation.
static void	distanceBetween(double startLatitude, double startLongitude, double endLatitude, double endLongitude, float[] results) Computes the approximate distance in meters between two locations, and optionally the initial and final bearings of the shortest path between them.
float	distanceTo(Location dest) Returns the approximate distance in meters between this location and the given location.
float	getAccuracy() Returns the accuracy of the fix in meters.
double	getAltitude() Returns the altitude of this fix.
float	getBearing() Returns the direction of travel in degrees East of true North.
Bundle	getExtras() Returns additional provider-specific information about the location fix as a Bundle.
double	getLatitude() Returns the latitude of this fix.
double	getLongitude() Returns the longitude of this fix.
String	getProvider() Returns the name of the provider that generated this fix, or null if it is not associated with a provider.
float	getSpeed() Returns the speed of the device over ground in meters/second.
long	getTime() Returns the UTC time of this fix, in milliseconds since January 1, 1970.
boolean	hasAccuracy() Returns true if the provider is able to report accuracy information, false otherwise.
boolean	hasAltitude() Returns true if this fix contains altitude information, false otherwise.
boolean	hasBearing() Returns true if the provider is able to report bearing information, false otherwise.
boolean	hasSpeed() Returns true if this fix contains speed information, false otherwise.
void	removeAccuracy() Clears the accuracy of this fix.
void	removeAltitude() Clears the altitude of this fix.
void	removeBearing() Clears the bearing of this fix.
void	removeSpeed() Clears the speed of this fix.
void	reset() Clears the contents of the location.
void	set(Location l) Sets the contents of the location to the values from the given location.
void	setAccuracy(float accuracy) Sets the accuracy of this fix.
void	setAltitude(double altitude) Sets the altitude of this fix.
void	setBearing(float bearing) Sets the bearing of this fix.
void	setExtras(Bundle extras) Sets the extra information associated with this fix to the given Bundle.
void	setLatitude(double latitude) Sets the latitude of this fix.
void	setLongitude(double longitude) Sets the longitude of this fix.
void	setProvider(String provider) Sets the name of the provider that generated this fix.
void	setSpeed(float speed) Sets the speed of this fix, in meters/second.
void	setTime(long time) Sets the UTC time of this fix, in milliseconds since January 1, 1970.
String	toString() Returns a string containing a concise, human-readable description of the receiver.
void	writeToParcel(Parcel parcel, int flags) Flatten this object in to a Parcel.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

FORMAT_DEGREES

public static final int FORMAT_DEGREES

Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD.DDDDD where D indicates degrees.

See Also:

Constant Field Values

FORMAT_MINUTES

public static final int FORMAT_MINUTES

Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD:MM.MMMMM" where D indicates degrees and M indicates minutes of arc (1 minute = 1/60th of a degree).

See Also:

Constant Field Values

FORMAT_SECONDS

public static final int FORMAT_SECONDS

Constant used to specify formatting of a latitude or longitude in the form "DDD:MM:SS.SSSSS" where D indicates degrees, M indicates minutes of arc, and S indicates seconds of arc (1 minute = 1/60th of a degree, 1 second = 1/3600th of a degree).

See Also:

Constant Field Values

CREATOR

public static final Parcelable.Creator<Location> CREATOR

Constructor Detail

Location

public Location(String provider)

Constructs a new Location. By default, time, latitude, longitude, and numSatellites are 0; hasAltitude, hasSpeed, and hasBearing are false; and there is no extra information.

Parameters:

provider - the name of the location provider that generated this location fix.

Location

public Location(Location l)

Constructs a new Location object that is a copy of the given location.

Method Detail

set

public void set(Location l)

Sets the contents of the location to the values from the given location.

reset

public void reset()

Clears the contents of the location.

convert

public static String convert(double coordinate,
                             int outputType)

Converts a coordinate to a String representation. The outputType may be one of FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS. The coordinate must be a valid double between -180.0 and 180.0.

Throws:

IllegalArgumentException - if coordinate is less than -180.0, greater than 180.0, or is not a number.

IllegalArgumentException - if outputType is not one of FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS.

convert

public static double convert(String coordinate)

Converts a String in one of the formats described by FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS into a double.

Throws:

NullPointerException - if coordinate is null

IllegalArgumentException - if the coordinate is not in one of the valid formats.

distanceBetween

public static void distanceBetween(double startLatitude,
                                   double startLongitude,
                                   double endLatitude,
                                   double endLongitude,
                                   float[] results)

Computes the approximate distance in meters between two locations, and optionally the initial and final bearings of the shortest path between them. Distance and bearing are defined using the WGS84 ellipsoid.

The computed distance is stored in results[0]. If results has length 2 or greater, the initial bearing is stored in results[1]. If results has length 3 or greater, the final bearing is stored in results[2].

Parameters:

startLatitude - the starting latitude

startLongitude - the starting longitude

endLatitude - the ending latitude

endLongitude - the ending longitude

results - an array of floats to hold the results

Throws:

IllegalArgumentException - if results is null or has length < 1

distanceTo

public float distanceTo(Location dest)

Returns the approximate distance in meters between this location and the given location. Distance is defined using the WGS84 ellipsoid.

Parameters:

dest - the destination location

Returns:

the approximate distance in meters

bearingTo

public float bearingTo(Location dest)

Returns the approximate initial bearing in degrees East of true North when traveling along the shortest path between this location and the given location. The shortest path is defined using the WGS84 ellipsoid. Locations that are (nearly) antipodal may produce meaningless results.

Parameters:

dest - the destination location

Returns:

the initial bearing in degrees

getProvider

public String getProvider()

Returns the name of the provider that generated this fix, or null if it is not associated with a provider.

setProvider

public void setProvider(String provider)

Sets the name of the provider that generated this fix.

getTime

public long getTime()

Returns the UTC time of this fix, in milliseconds since January 1, 1970.

setTime

public void setTime(long time)

Sets the UTC time of this fix, in milliseconds since January 1, 1970.

getLatitude

public double getLatitude()

Returns the latitude of this fix.

setLatitude

public void setLatitude(double latitude)

Sets the latitude of this fix.

getLongitude

public double getLongitude()

Returns the longitude of this fix.

setLongitude

public void setLongitude(double longitude)

Sets the longitude of this fix.

hasAltitude

public boolean hasAltitude()

Returns true if this fix contains altitude information, false otherwise.

getAltitude

public double getAltitude()

Returns the altitude of this fix. If hasAltitude() is false, 0.0f is returned.

setAltitude

public void setAltitude(double altitude)

Sets the altitude of this fix. Following this call, hasAltitude() will return true.

removeAltitude

public void removeAltitude()

Clears the altitude of this fix. Following this call, hasAltitude() will return false.

hasSpeed

public boolean hasSpeed()

Returns true if this fix contains speed information, false otherwise. The default implementation returns false.

getSpeed

public float getSpeed()

Returns the speed of the device over ground in meters/second. If hasSpeed() is false, 0.0f is returned.

setSpeed

public void setSpeed(float speed)

Sets the speed of this fix, in meters/second. Following this call, hasSpeed() will return true.

removeSpeed

public void removeSpeed()

Clears the speed of this fix. Following this call, hasSpeed() will return false.

hasBearing

public boolean hasBearing()

Returns true if the provider is able to report bearing information, false otherwise. The default implementation returns false.

getBearing

public float getBearing()

Returns the direction of travel in degrees East of true North. If hasBearing() is false, 0.0 is returned.

setBearing

public void setBearing(float bearing)

Sets the bearing of this fix. Following this call, hasBearing() will return true.

removeBearing

public void removeBearing()

Clears the bearing of this fix. Following this call, hasBearing() will return false.

hasAccuracy

public boolean hasAccuracy()

Returns true if the provider is able to report accuracy information, false otherwise. The default implementation returns false.

getAccuracy

public float getAccuracy()

Returns the accuracy of the fix in meters. If hasAccuracy() is false, 0.0 is returned.

setAccuracy

public void setAccuracy(float accuracy)

Sets the accuracy of this fix. Following this call, hasAccuracy() will return true.

removeAccuracy

public void removeAccuracy()

Clears the accuracy of this fix. Following this call, hasAccuracy() will return false.

getExtras

public Bundle getExtras()

Returns additional provider-specific information about the location fix as a Bundle. The keys and values are determined by the provider. If no additional information is available, null is returned.

A number of common key/value pairs are listed below. Providers that use any of the keys on this list must provide the corresponding value as described below.

• satellites - the number of satellites used to derive the fix

setExtras

public void setExtras(Bundle extras)

Sets the extra information associated with this fix to the given Bundle.

toString

public String toString()

Description copied from class: Object

Returns a string containing a concise, human-readable description of the receiver.

Overrides:

toString in class Object

Returns:

String a printable representation for the receiver.

describeContents

public int describeContents()

Description copied from interface: Parcelable

Describe the kinds of special objects contained in this Parcelable's marshalled representation.

Specified by:

describeContents in interface Parcelable

Returns:

a bitmask indicating the set of special object types marshalled by the Parcelable.

writeToParcel

public void writeToParcel(Parcel parcel,
                          int flags)

Description copied from interface: Parcelable

Flatten this object in to a Parcel.

Specified by:

writeToParcel in interface Parcelable

Parameters:

parcel - The Parcel in which the object should be written.

flags - Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE.