Skip to content

Most visited

Recently visited

navigation

Location

public class Location
extends Object implements Parcelable

java.lang.Object
   ↳ android.location.Location


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

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 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 instance's marshaled 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 horizontal accuracy of this location, radial, in meters.

double getAltitude()

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

float getBearing()

Get the bearing, in degrees.

float getBearingAccuracyDegrees()

Get the estimated bearing accuracy of this location, 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.

float getSpeedAccuracyMetersPerSecond()

Get the estimated speed accuracy of this location, in meters per second.

long getTime()

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

float getVerticalAccuracyMeters()

Get the estimated vertical accuracy of this location, in meters.

boolean hasAccuracy()

True if this location has a horizontal accuracy.

boolean hasAltitude()

True if this location has an altitude.

boolean hasBearing()

True if this location has a bearing.

boolean hasBearingAccuracy()

True if this location has a bearing accuracy.

boolean hasSpeed()

True if this location has a speed.

boolean hasSpeedAccuracy()

True if this location has a speed accuracy.

boolean hasVerticalAccuracy()

True if this location has a vertical accuracy.

boolean isFromMockProvider()

Returns true if the Location came from a mock provider.

void removeAccuracy()

This method was deprecated in API level 26. use a new Location object for location updates.

void removeAltitude()

This method was deprecated in API level 26. use a new Location object for location updates.

void removeBearing()

This method was deprecated in API level 26. use a new Location object for location updates.

void removeSpeed()

This method was deprecated in API level 26. use a new Location object for location updates.

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

Set the estimated horizontal 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 setBearingAccuracyDegrees(float bearingAccuracyDegrees)

Set the estimated bearing accuracy of this location, 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 setSpeedAccuracyMetersPerSecond(float speedAccuracyMeterPerSecond)

Set the estimated speed accuracy of this location, meters per second.

void setTime(long time)

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

void setVerticalAccuracyMeters(float verticalAccuracyMeters)

Set the estimated vertical accuracy of this location, meters.

String toString()

Returns a string representation of the object.

void writeToParcel(Parcel parcel, int flags)

Flatten this object in to a Parcel.

Inherited methods

From class java.lang.Object
From interface android.os.Parcelable

Constants

FORMAT_DEGREES

added in API level 1
int FORMAT_DEGREES

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

Constant Value: 0 (0x00000000)

FORMAT_MINUTES

added in API level 1
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).

Constant Value: 1 (0x00000001)

FORMAT_SECONDS

added in API level 1
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).

Constant Value: 2 (0x00000002)

Fields

CREATOR

added in API level 1
Creator<Location> CREATOR

Public constructors

Location

added in API level 1
Location (String provider)

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

Location

added in API level 1
Location (Location l)

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

Parameters
l Location

Public methods

bearingTo

added in API level 1
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 Location: the destination location

Returns
float the initial bearing in degrees

convert

added in API level 1
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. 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.

convert

added in API level 1
double convert (String coordinate)

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.

describeContents

added in API level 1
int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int a bitmask indicating the set of special object types marshaled by this Parcelable object instance.

distanceBetween

added in API level 1
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 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

distanceTo

added in API level 1
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 Location: the destination location

Returns
float the approximate distance in meters

dump

added in API level 3
void dump (Printer pw, 
                String prefix)

Parameters
pw Printer

prefix String

getAccuracy

added in API level 1
float getAccuracy ()

Get the estimated horizontal accuracy of this location, radial, in meters.

We define horizontal 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 a horizontal accuracy, then 0.0 is returned. All locations generated by the LocationManager include horizontal accuracy.

Returns
float

getAltitude

added in API level 1
double getAltitude ()

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

getBearing

added in API level 1
float getBearing ()

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

getBearingAccuracyDegrees

added in API level 26
float getBearingAccuracyDegrees ()

Get the estimated bearing accuracy of this location, in degrees.

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

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

Returns
float

getElapsedRealtimeNanos

added in API level 17
long getElapsedRealtimeNanos ()

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.

getExtras

added in API level 1
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

Returns
Bundle

getLatitude

added in API level 1
double getLatitude ()

Get the latitude, in degrees.

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

Returns
double

getLongitude

added in API level 1
double getLongitude ()

Get the longitude, in degrees.

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

Returns
double

getProvider

added in API level 1
String getProvider ()

Returns the name of the provider that generated this fix.

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

getSpeed

added in API level 1
float getSpeed ()

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

getSpeedAccuracyMetersPerSecond

added in API level 26
float getSpeedAccuracyMetersPerSecond ()

Get the estimated speed accuracy of this location, in meters per second.

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

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

Returns
float

getTime

added in API level 1
long getTime ()

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.

getVerticalAccuracyMeters

added in API level 26
float getVerticalAccuracyMeters ()

Get the estimated vertical accuracy of this location, in meters.

We define vertical accuracy as the radius of 68% confidence. In other words, if you draw a circle centered at this location's altitude, and with a radius equal to the vertical accuracy, then there is a 68% probability that the true altitude 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.

If this location does not have a vertical accuracy, then 0.0 is returned.

Returns
float

hasAccuracy

added in API level 1
boolean hasAccuracy ()

True if this location has a horizontal accuracy.

All locations generated by the LocationManager have an horizontal accuracy.

Returns
boolean

hasAltitude

added in API level 1
boolean hasAltitude ()

True if this location has an altitude.

Returns
boolean

hasBearing

added in API level 1
boolean hasBearing ()

True if this location has a bearing.

Returns
boolean

hasBearingAccuracy

added in API level 26
boolean hasBearingAccuracy ()

True if this location has a bearing accuracy.

Returns
boolean

hasSpeed

added in API level 1
boolean hasSpeed ()

True if this location has a speed.

Returns
boolean

hasSpeedAccuracy

added in API level 26
boolean hasSpeedAccuracy ()

True if this location has a speed accuracy.

Returns
boolean

hasVerticalAccuracy

added in API level 26
boolean hasVerticalAccuracy ()

True if this location has a vertical accuracy.

Returns
boolean

isFromMockProvider

added in API level 18
boolean isFromMockProvider ()

Returns true if the Location came from a mock provider.

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

removeAccuracy

added in API level 1
void removeAccuracy ()

This method was deprecated in API level 26.
use a new Location object for location updates.

Remove the horizontal accuracy from this location.

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

removeAltitude

added in API level 1
void removeAltitude ()

This method was deprecated in API level 26.
use a new Location object for location updates.

Remove the altitude from this location.

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

removeBearing

added in API level 1
void removeBearing ()

This method was deprecated in API level 26.
use a new Location object for location updates.

Remove the bearing from this location.

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

removeSpeed

added in API level 1
void removeSpeed ()

This method was deprecated in API level 26.
use a new Location object for location updates.

Remove the speed from this location.

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

reset

added in API level 1
void reset ()

Clears the contents of the location.

set

added in API level 1
void set (Location l)

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

Parameters
l Location

setAccuracy

added in API level 1
void setAccuracy (float horizontalAccuracy)

Set the estimated horizontal accuracy of this location, meters.

See getAccuracy() for the definition of horizontal accuracy.

Following this call hasAccuracy() will return true.

Parameters
horizontalAccuracy float

setAltitude

added in API level 1
void setAltitude (double altitude)

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

Following this call hasAltitude() will return true.

Parameters
altitude double

setBearing

added in API level 1
void setBearing (float bearing)

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

setBearingAccuracyDegrees

added in API level 26
void setBearingAccuracyDegrees (float bearingAccuracyDegrees)

Set the estimated bearing accuracy of this location, degrees.

See getBearingAccuracyDegrees() for the definition of bearing accuracy.

Following this call hasBearingAccuracy() will return true.

Parameters
bearingAccuracyDegrees float

setElapsedRealtimeNanos

added in API level 17
void setElapsedRealtimeNanos (long time)

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.

setExtras

added in API level 1
void setExtras (Bundle extras)

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

Parameters
extras Bundle

setLatitude

added in API level 1
void setLatitude (double latitude)

Set the latitude, in degrees.

Parameters
latitude double

setLongitude

added in API level 1
void setLongitude (double longitude)

Set the longitude, in degrees.

Parameters
longitude double

setProvider

added in API level 1
void setProvider (String provider)

Sets the name of the provider that generated this fix.

Parameters
provider String

setSpeed

added in API level 1
void setSpeed (float speed)

Set the speed, in meters/second over ground.

Following this call hasSpeed() will return true.

Parameters
speed float

setSpeedAccuracyMetersPerSecond

added in API level 26
void setSpeedAccuracyMetersPerSecond (float speedAccuracyMeterPerSecond)

Set the estimated speed accuracy of this location, meters per second.

See getSpeedAccuracyMetersPerSecond() for the definition of speed accuracy.

Following this call hasSpeedAccuracy() will return true.

Parameters
speedAccuracyMeterPerSecond float

setTime

added in API level 1
void setTime (long time)

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

setVerticalAccuracyMeters

added in API level 26
void setVerticalAccuracyMeters (float verticalAccuracyMeters)

Set the estimated vertical accuracy of this location, meters.

See getVerticalAccuracyMeters() for the definition of vertical accuracy.

Following this call hasVerticalAccuracy() will return true.

Parameters
verticalAccuracyMeters float

toString

added in API level 1
String toString ()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

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

Returns
String a string representation of the object.

writeToParcel

added in API level 1
void writeToParcel (Parcel parcel, 
                int flags)

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.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)