Android APIs
public class

Location

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

Class Overview

A data class representing a geographic location.

A location can consist of a latitude, longitude, timestamp, and other information such as bearing, altitude and velocity.

All locations generated by the LocationManager are guaranteed to have a valid latitude, longitude, and timestamp (both UTC time and elapsed real-time since boot), all other parameters are optional.

Summary

Constants
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
Fields
public static final Creator<Location> CREATOR
Public Constructors
Location(String provider)
Construct a new Location with a named provider.
Location(Location l)
Construct a new Location object that is copied from an existing one.
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()
Get the estimated accuracy of this location, in meters.
double getAltitude()
Get the altitude if available, in meters above the WGS 84 reference ellipsoid.
float getBearing()
Get the bearing, in degrees.
long getElapsedRealtimeNanos()
Return the time of this fix, in elapsed real-time since system boot.
Bundle getExtras()
Returns additional provider-specific information about the location fix as a Bundle.
double getLatitude()
Get the latitude, in degrees.
double getLongitude()
Get the longitude, in degrees.
String getProvider()
Returns the name of the provider that generated this fix.
float getSpeed()
Get the speed if it is available, in meters/second over ground.
long getTime()
Return the UTC time of this fix, in milliseconds since January 1, 1970.
boolean hasAccuracy()
True if this location has an accuracy.
boolean hasAltitude()
True if this location has an altitude.
boolean hasBearing()
True if this location has a bearing.
boolean hasSpeed()
True if this location has a speed.
boolean isFromMockProvider()
Returns true if the Location came from a mock provider.
void removeAccuracy()
Remove the accuracy from this location.
void removeAltitude()
Remove the altitude from this location.
void removeBearing()
Remove the bearing from this location.
void removeSpeed()
Remove the speed from this location.
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)
Set the estimated accuracy of this location, meters.
void setAltitude(double altitude)
Set the altitude, in meters above the WGS 84 reference ellipsoid.
void setBearing(float bearing)
Set the bearing, in degrees.
void setElapsedRealtimeNanos(long time)
Set the time of this fix, in elapsed real-time since system boot.
void setExtras(Bundle extras)
Sets the extra information associated with this fix to the given Bundle.
void setLatitude(double latitude)
Set the latitude, in degrees.
void setLongitude(double longitude)
Set the longitude, in degrees.
void setProvider(String provider)
Sets the name of the provider that generated this fix.
void setSpeed(float speed)
Set the speed, in meters/second over ground.
void setTime(long time)
Set 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 int FORMAT_DEGREES

Added in 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

Added in 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

Added in 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)

Fields

public static final Creator<Location> CREATOR

Added in API level 1

Public Constructors

public Location (String provider)

Added in API level 1

Construct a new Location with a named provider.

By default time, latitude and longitude are 0, and the location has no bearing, altitude, speed, accuracy or extras.

Parameters
provider String: the name of the provider that generated this location

public Location (Location l)

Added in API level 1

Construct a new Location object that is copied from an existing one.

Parameters
l Location

Public Methods

public float bearingTo (Location dest)

Added in 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 Location: the destination location
Returns
float the initial bearing in degrees

public static double convert (String coordinate)

Added in API level 1

Converts a String in one of the formats described by FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS into a double. This conversion is performed in a locale agnostic method, and so is not guaranteed to round-trip with convert(double, int).

Parameters
coordinate String
Returns
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)

Added in 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. This conversion is performed in a method that is dependent on the default locale, and so is not guaranteed to round-trip with convert(String).

Parameters
coordinate double
outputType int
Returns
String
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 ()

Added in API level 1

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

Returns
int 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)

Added in 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 double: the starting latitude
startLongitude double: the starting longitude
endLatitude double: the ending latitude
endLongitude double: the ending longitude
results float: an array of floats to hold the results
Throws
IllegalArgumentException if results is null or has length < 1

public float distanceTo (Location dest)

Added in 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 Location: the destination location
Returns
float the approximate distance in meters

public void dump (Printer pw, String prefix)

Added in API level 3

Parameters
pw Printer
prefix String

public float getAccuracy ()

Added in API level 1

Get the estimated accuracy of this location, in meters.

We define accuracy as the radius of 68% confidence. In other words, if you draw a circle centered at this location's latitude and longitude, and with a radius equal to the accuracy, then there is a 68% probability that the true location is inside the circle.

In statistical terms, it is assumed that location errors are random with a normal distribution, so the 68% confidence circle represents one standard deviation. Note that in practice, location errors do not always follow such a simple distribution.

This accuracy estimation is only concerned with horizontal accuracy, and does not indicate the accuracy of bearing, velocity or altitude if those are included in this Location.

If this location does not have an accuracy, then 0.0 is returned. All locations generated by the LocationManager include an accuracy.

Returns
float

public double getAltitude ()

Added in API level 1

Get the altitude if available, in meters above the WGS 84 reference ellipsoid.

If this location does not have an altitude then 0.0 is returned.

Returns
double

public float getBearing ()

Added in API level 1

Get the bearing, in degrees.

Bearing is the horizontal direction of travel of this device, and is not related to the device orientation. It is guaranteed to be in the range (0.0, 360.0] if the device has a bearing.

If this location does not have a bearing then 0.0 is returned.

Returns
float

public long getElapsedRealtimeNanos ()

Added in API level 17

Return the time of this fix, in elapsed real-time since system boot.

This value can be reliably compared to elapsedRealtimeNanos(), to calculate the age of a fix and to compare Location fixes. This is reliable because elapsed real-time is guaranteed monotonic for each system boot and continues to increment even when the system is in deep sleep (unlike getTime().

All locations generated by the LocationManager are guaranteed to have a valid elapsed real-time.

Returns
long elapsed real-time of fix, in nanoseconds since system boot.

public Bundle getExtras ()

Added in 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

Returns
Bundle

public double getLatitude ()

Added in API level 1

Get the latitude, in degrees.

All locations generated by the LocationManager will have a valid latitude.

Returns
double

public double getLongitude ()

Added in API level 1

Get the longitude, in degrees.

All locations generated by the LocationManager will have a valid longitude.

Returns
double

public String getProvider ()

Added in API level 1

Returns the name of the provider that generated this fix.

Returns
String the provider, or null if it has not been set

public float getSpeed ()

Added in API level 1

Get the speed if it is available, in meters/second over ground.

If this location does not have a speed then 0.0 is returned.

Returns
float

public long getTime ()

Added in API level 1

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

Note that the UTC time on a device is not monotonic: it can jump forwards or backwards unpredictably. So always use getElapsedRealtimeNanos() when calculating time deltas.

On the other hand, getTime() is useful for presenting a human readable time to the user, or for carefully comparing location fixes across reboot or across devices.

All locations generated by the LocationManager are guaranteed to have a valid UTC time, however remember that the system time may have changed since the location was generated.

Returns
long time of fix, in milliseconds since January 1, 1970.

public boolean hasAccuracy ()

Added in API level 1

True if this location has an accuracy.

All locations generated by the LocationManager have an accuracy.

Returns
boolean

public boolean hasAltitude ()

Added in API level 1

True if this location has an altitude.

Returns
boolean

public boolean hasBearing ()

Added in API level 1

True if this location has a bearing.

Returns
boolean

public boolean hasSpeed ()

Added in API level 1

True if this location has a speed.

Returns
boolean

public boolean isFromMockProvider ()

Added in API level 18

Returns true if the Location came from a mock provider.

Returns
boolean true if this Location came from a mock provider, false otherwise

public void removeAccuracy ()

Added in API level 1

Remove the accuracy from this location.

Following this call hasAccuracy() will return false, and getAccuracy() will return 0.0.

public void removeAltitude ()

Added in API level 1

Remove the altitude from this location.

Following this call hasAltitude() will return false, and getAltitude() will return 0.0.

public void removeBearing ()

Added in API level 1

Remove the bearing from this location.

Following this call hasBearing() will return false, and getBearing() will return 0.0.

public void removeSpeed ()

Added in API level 1

Remove the speed from this location.

Following this call hasSpeed() will return false, and getSpeed() will return 0.0.

public void reset ()

Added in API level 1

Clears the contents of the location.

public void set (Location l)

Added in API level 1

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

Parameters
l Location

public void setAccuracy (float accuracy)

Added in API level 1

Set the estimated accuracy of this location, meters.

See getAccuracy() for the definition of accuracy.

Following this call hasAccuracy() will return true.

Parameters
accuracy float

public void setAltitude (double altitude)

Added in API level 1

Set the altitude, in meters above the WGS 84 reference ellipsoid.

Following this call hasAltitude() will return true.

Parameters
altitude double

public void setBearing (float bearing)

Added in API level 1

Set the bearing, in degrees.

Bearing is the horizontal direction of travel of this device, and is not related to the device orientation.

The input will be wrapped into the range (0.0, 360.0].

Parameters
bearing float

public void setElapsedRealtimeNanos (long time)

Added in API level 17

Set the time of this fix, in elapsed real-time since system boot.

Parameters
time long: elapsed real-time of fix, in nanoseconds since system boot.

public void setExtras (Bundle extras)

Added in API level 1

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

Parameters
extras Bundle

public void setLatitude (double latitude)

Added in API level 1

Set the latitude, in degrees.

Parameters
latitude double

public void setLongitude (double longitude)

Added in API level 1

Set the longitude, in degrees.

Parameters
longitude double

public void setProvider (String provider)

Added in API level 1

Sets the name of the provider that generated this fix.

Parameters
provider String

public void setSpeed (float speed)

Added in API level 1

Set the speed, in meters/second over ground.

Following this call hasSpeed() will return true.

Parameters
speed float

public void setTime (long time)

Added in API level 1

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

Parameters
time long: UTC time of this fix, in milliseconds since January 1, 1970

public String toString ()

Added in 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
String a printable representation of this object.

public void writeToParcel (Parcel parcel, int flags)

Added in API level 1

Flatten this object in to a Parcel.

Parameters
parcel Parcel: The Parcel in which the object should be written.
flags int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE.