public class

Location

extends Object
implements Parcelable
java.lang.Object
   ↳ android.location.Location

Class Overview

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.

Summary

Constants
Creator<Location> CREATOR
int FORMAT_DEGREES Constant used to specify formatting of a latitude or longitude in the form "[+-]DDD.DDDDD where D indicates degrees.
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).
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).
[Expand]
Inherited Constants
From interface android.os.Parcelable
Public Constructors
Location(String provider)
Constructs a new Location.
Location(Location l)
Constructs a new Location object that is a copy of the given location.
Public Methods
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 double convert(String coordinate)
Converts a String in one of the formats described by FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS into a double.
static String convert(double coordinate, int outputType)
Converts a coordinate to a String representation.
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.
void dump(Printer pw, String prefix)
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 this object.
void writeToParcel(Parcel parcel, int flags)
Flatten this object in to a Parcel.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.os.Parcelable

Constants

public static final Creator<Location> CREATOR

Since: API Level 1

public static final int FORMAT_DEGREES

Since: API Level 1

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

Constant Value: 0 (0x00000000)

public static final int FORMAT_MINUTES

Since: API Level 1

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

Constant Value: 1 (0x00000001)

public static final int FORMAT_SECONDS

Since: API Level 1

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

Constant Value: 2 (0x00000002)

Public Constructors

public Location (String provider)

Since: API Level 1

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.

public Location (Location l)

Since: API Level 1

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

Public Methods

public float bearingTo (Location dest)

Since: API Level 1

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

public static double convert (String coordinate)

Since: API Level 1

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.

public static String convert (double coordinate, int outputType)

Since: API Level 1

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.

public int describeContents ()

Since: API Level 1

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

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

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

Since: API Level 1

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

public float distanceTo (Location dest)

Since: API Level 1

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

public void dump (Printer pw, String prefix)

Since: API Level 3

public float getAccuracy ()

Since: API Level 1

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

public double getAltitude ()

Since: API Level 1

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

public float getBearing ()

Since: API Level 1

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

public Bundle getExtras ()

Since: API Level 1

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

public double getLatitude ()

Since: API Level 1

Returns the latitude of this fix.

public double getLongitude ()

Since: API Level 1

Returns the longitude of this fix.

public String getProvider ()

Since: API Level 1

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

public float getSpeed ()

Since: API Level 1

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

public long getTime ()

Since: API Level 1

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

public boolean hasAccuracy ()

Since: API Level 1

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

public boolean hasAltitude ()

Since: API Level 1

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

public boolean hasBearing ()

Since: API Level 1

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

public boolean hasSpeed ()

Since: API Level 1

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

public void removeAccuracy ()

Since: API Level 1

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

public void removeAltitude ()

Since: API Level 1

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

public void removeBearing ()

Since: API Level 1

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

public void removeSpeed ()

Since: API Level 1

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

public void reset ()

Since: API Level 1

Clears the contents of the location.

public void set (Location l)

Since: API Level 1

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

public void setAccuracy (float accuracy)

Since: API Level 1

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

public void setAltitude (double altitude)

Since: API Level 1

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

public void setBearing (float bearing)

Since: API Level 1

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

public void setExtras (Bundle extras)

Since: API Level 1

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

public void setLatitude (double latitude)

Since: API Level 1

Sets the latitude of this fix.

public void setLongitude (double longitude)

Since: API Level 1

Sets the longitude of this fix.

public void setProvider (String provider)

Since: API Level 1

Sets the name of the provider that generated this fix.

public void setSpeed (float speed)

Since: API Level 1

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

public void setTime (long time)

Since: API Level 1

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

public String toString ()

Since: API Level 1

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression: 

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Returns
  • a printable representation of this object.

public void writeToParcel (Parcel parcel, int flags)

Since: API Level 1

Flatten this object in to a Parcel.

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