Location

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.

Constant Value: 0 (0x00000000)

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

Constant Value: 1 (0x00000001)

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

Constant Value: 2 (0x00000002)

CREATOR

public static final Creator<Location> CREATOR

Location

public Location (String provider)

Constructs a new location with a named provider. By default all values are zero, and no optional values are present.

Location

public Location (Location location)

Constructs a new location copied from the given location.

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.

convert

public static String convert (double coordinate, 
                int outputType)

Converts a latitude/longitude coordinate to a String representation. The outputType must be one of FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS. The coordinate must be a number between -180.0 and 180.0, inclusive. This conversion is performed in a method that is dependent on the default locale, and so is not guaranteed to round-trip with convert(java.lang.String).

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. This conversion is performed in a locale agnostic method, and so is not guaranteed to round-trip with convert(double, int).

describeContents

public 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(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

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

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.

dump

public void dump (Printer pw, 
                String prefix)

This method was deprecated in API level 33.
Prefer to use toString() along with whatever custom formatting is required instead of this method. It is not this class's job to manage print representations.

Dumps location information to the given Printer.

equals

public boolean equals (Object o)

Location equality is provided primarily for test purposes. Comparing locations for equality in production may indicate incorrect assumptions, and should be avoided whenever possible.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

• It is reflexive: for any non-null reference value x, x.equals(x) should return true.
• It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
• It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
• For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

getAccuracy

public float getAccuracy ()

Returns the estimated horizontal accuracy radius in meters of this location at the 68th percentile confidence level. This means that there is a 68% chance that the true location of the device is within a distance of this uncertainty of the reported location. Another way of putting this is that if a circle with a radius equal to this accuracy is drawn around the reported location, there is a 68% chance that the true location falls within this circle. This accuracy value is only valid for horizontal positioning, and not vertical positioning.

This is only valid if hasAccuracy() is true. All locations generated by the LocationManager include horizontal accuracy.

getAltitude

public double getAltitude ()

The altitude of this location in meters above the WGS84 reference ellipsoid.

This is only valid if hasAltitude() is true.

getBearing

public float getBearing ()

Returns the bearing at the time of this location in degrees. Bearing is the horizontal direction of travel of this device and is unrelated to the device orientation. The bearing is guaranteed to be in the range [0, 360).

This is only valid if hasBearing() is true.

getBearingAccuracyDegrees

public float getBearingAccuracyDegrees ()

Returns the estimated bearing accuracy in degrees of this location at the 68th percentile confidence level. This means that there is 68% chance that the true bearing at the time of this location falls within getBearing() ()} +/- this uncertainty.

This is only valid if hasBearingAccuracy() ()} is true.

getElapsedRealtimeAgeMillis

public long getElapsedRealtimeAgeMillis (long referenceRealtimeMs)

A convenience method that returns the age of this location with respect to the given reference elapsed realtime.

getElapsedRealtimeAgeMillis

public long getElapsedRealtimeAgeMillis ()

A convenience methods that returns the age of this location in milliseconds with respect to the current elapsed realtime.

getElapsedRealtimeMillis

public long getElapsedRealtimeMillis ()

Return the time of this fix in milliseconds of elapsed realtime since system boot.

getElapsedRealtimeNanos

public long getElapsedRealtimeNanos ()

Return the time of this fix in nanoseconds of elapsed realtime since system boot.

This value can be compared with SystemClock.elapsedRealtimeNanos() to reliably order or compare locations. This is reliable because elapsed realtime is guaranteed to be monotonic and continues to increment even when the system is in deep sleep (unlike getTime()). However, since elapsed realtime is with reference to system boot, it does not make sense to use this value to order or compare locations across boot cycles or devices.

All locations generated by the LocationManager are guaranteed to have a valid elapsed realtime set.

getElapsedRealtimeUncertaintyNanos

public double getElapsedRealtimeUncertaintyNanos ()

Get the uncertainty in nanoseconds of the precision of getElapsedRealtimeNanos() at the 68th percentile confidence level. This means that there is 68% chance that the true elapsed realtime of this location is within getElapsedRealtimeNanos() +/- this uncertainty.

This is only valid if hasElapsedRealtimeUncertaintyNanos() is true.

getExtras

public Bundle getExtras ()

Returns an optional bundle of additional information associated with this location. The keys and values within the bundle are determined by the location provider.

Common key/value pairs are listed below. There is no guarantee that these key/value pairs will be present for any location.

• satellites - the number of satellites used to derive a GNSS fix. This key was deprecated in API 34 because the information can be obtained through more accurate means, such as by referencing GnssStatus#usedInFix.

getLatitude

public double getLatitude ()

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

getLongitude

public double getLongitude ()

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

getMslAltitudeAccuracyMeters

public float getMslAltitudeAccuracyMeters ()

Returns the estimated Mean Sea Level altitude accuracy in meters of this location at the 68th percentile confidence level. This means that there is 68% chance that the true Mean Sea Level altitude of this location falls within getMslAltitudeMeters() +/- this uncertainty.

This is only valid if hasMslAltitudeAccuracy() is true.

getMslAltitudeMeters

public double getMslAltitudeMeters ()

Returns the Mean Sea Level altitude of this location in meters.

This is only valid if hasMslAltitude() is true.

getProvider

public String getProvider ()

Returns the name of the provider associated with this location.

getSpeed

public float getSpeed ()

Returns the speed at the time of this location in meters per second. Note that the speed returned here may be more accurate than would be obtained simply by calculating distance / time for sequential positions, such as if the Doppler measurements from GNSS satellites are taken into account.

This is only valid if hasSpeed() is true.

getSpeedAccuracyMetersPerSecond

public float getSpeedAccuracyMetersPerSecond ()

Returns the estimated speed accuracy in meters per second of this location at the 68th percentile confidence level. This means that there is 68% chance that the true speed at the time of this location falls within getSpeed() ()} +/- this uncertainty.

This is only valid if hasSpeedAccuracy() is true.

getTime

public long getTime ()

Returns the Unix epoch time of this location fix, in milliseconds since the start of the Unix epoch (00:00:00 January 1, 1970 UTC).

There is no guarantee that different locations have times set from the same clock. Locations derived from the LocationManager#GPS_PROVIDER are guaranteed to have their time originate from the clock in use by the satellite constellation that provided the fix. Locations derived from other providers may use any clock to set their time, though it is most common to use the device's Unix epoch time system clock (which may be incorrect).

Note that the device's Unix epoch time system clock is not monotonic; it can jump forwards or backwards unpredictably and may be changed at any time by the user, so this time should not be used to order or compare locations. Prefer getElapsedRealtimeNanos() for that purpose, as the elapsed realtime clock is guaranteed to be monotonic.

On the other hand, this method may be useful for presenting a human-readable time to the user, or as a heuristic for comparing location fixes across reboot or across devices.

All locations generated by the LocationManager are guaranteed to have this time set, however remember that the device's system clock may have changed since the location was generated.

getVerticalAccuracyMeters

public float getVerticalAccuracyMeters ()

Returns the estimated altitude accuracy in meters of this location at the 68th percentile confidence level. This means that there is 68% chance that the true altitude of this location falls within getAltitude() ()} +/- this uncertainty.

This is only valid if hasVerticalAccuracy() is true.

hasAccuracy

public boolean hasAccuracy ()

Returns true if this location has a horizontal accuracy, false otherwise.

hasAltitude

public boolean hasAltitude ()

Returns true if this location has an altitude, false otherwise.

hasBearing

public boolean hasBearing ()

True if this location has a bearing, false otherwise.

hasBearingAccuracy

public boolean hasBearingAccuracy ()

Returns true if this location has a bearing accuracy, false otherwise.

hasElapsedRealtimeUncertaintyNanos

public boolean hasElapsedRealtimeUncertaintyNanos ()

True if this location has an elapsed realtime uncertainty, false otherwise.

hasMslAltitude

public boolean hasMslAltitude ()

Returns true if this location has a Mean Sea Level altitude, false otherwise.

hasMslAltitudeAccuracy

public boolean hasMslAltitudeAccuracy ()

Returns true if this location has a Mean Sea Level altitude accuracy, false otherwise.

hasSpeed

public boolean hasSpeed ()

True if this location has a speed, false otherwise.

hasSpeedAccuracy

public boolean hasSpeedAccuracy ()

Returns true if this location has a speed accuracy, false otherwise.

hasVerticalAccuracy

public boolean hasVerticalAccuracy ()

Returns true if this location has a vertical accuracy, false otherwise.

hashCode

public int hashCode ()

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

The general contract of hashCode is:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
• If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

isComplete

public boolean isComplete ()

Return true if this location is considered complete. A location is considered complete if it has a non-null provider, accuracy, and non-zero time and elapsed realtime. The exact definition of completeness may change over time.

All locations supplied by the LocationManager are guaranteed to be complete.

isFromMockProvider

public boolean isFromMockProvider ()

This method was deprecated in API level 31.
Prefer isMock() instead.

Returns true if this is a mock location. If this location comes from the Android framework, this indicates that the location was provided by a test location provider, and thus may not be related to the actual location of the device.

isMock

public boolean isMock ()

Returns true if this location is marked as a mock location. If this location comes from the Android framework, this indicates that the location was provided by a test location provider, and thus may not be related to the actual location of the device.

removeAccuracy

public void removeAccuracy ()

Remove the horizontal accuracy from this location.

removeAltitude

public void removeAltitude ()

Removes the altitude from this location.

removeBearing

public void removeBearing ()

Remove the bearing from this location.

removeBearingAccuracy

public void removeBearingAccuracy ()

Remove the bearing accuracy from this location.

removeElapsedRealtimeUncertaintyNanos

public void removeElapsedRealtimeUncertaintyNanos ()

Removes the elapsed realtime uncertainty from this location.

removeMslAltitude

public void removeMslAltitude ()

Removes the Mean Sea Level altitude from this location.

removeMslAltitudeAccuracy

public void removeMslAltitudeAccuracy ()

Removes the Mean Sea Level altitude accuracy from this location.

removeSpeed

public void removeSpeed ()

Remove the speed from this location.

removeSpeedAccuracy

public void removeSpeedAccuracy ()

Remove the speed accuracy from this location.

removeVerticalAccuracy

public void removeVerticalAccuracy ()

Remove the vertical accuracy from this location.

reset

public void reset ()

Sets the provider to null, removes all optional fields, and sets the values of all other fields to zero.

set

public void set (Location location)

Turns this location into a copy of the given location.

setAccuracy

public void setAccuracy (float horizontalAccuracyMeters)

Set the horizontal accuracy in meters of this location.

setAltitude

public void setAltitude (double altitudeMeters)

Set the altitude of this location in meters above the WGS84 reference ellipsoid.

setBearing

public void setBearing (float bearingDegrees)

Set the bearing at the time of this location, in degrees. The given bearing will be converted into the range [0, 360).

Note: passing in extremely high or low floating point values to this function may produce strange results due to the intricacies of floating point math.

setBearingAccuracyDegrees

public void setBearingAccuracyDegrees (float bearingAccuracyDegrees)

Set the bearing accuracy in degrees of this location.

setElapsedRealtimeNanos

public void setElapsedRealtimeNanos (long elapsedRealtimeNs)

Set the time of this location in nanoseconds of elapsed realtime since system boot.

setElapsedRealtimeUncertaintyNanos

public void setElapsedRealtimeUncertaintyNanos (double elapsedRealtimeUncertaintyNs)

Sets the uncertainty in nanoseconds of the precision of the elapsed realtime timestamp at a 68% confidence level.

setExtras

public void setExtras (Bundle extras)

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

Note this stores a copy of the given extras, so any changes to extras after calling this method won't be reflected in the location bundle.

setLatitude

public void setLatitude (double latitudeDegrees)

Set the latitude of this location.

setLongitude

public void setLongitude (double longitudeDegrees)

Set the longitude of this location.

setMock

public void setMock (boolean mock)

Sets whether this location is marked as a mock location.

setMslAltitudeAccuracyMeters

public void setMslAltitudeAccuracyMeters (float mslAltitudeAccuracyMeters)

Sets the Mean Sea Level altitude accuracy of this location in meters.

setMslAltitudeMeters

public void setMslAltitudeMeters (double mslAltitudeMeters)

Sets the Mean Sea Level altitude of this location in meters.

setProvider

public void setProvider (String provider)

Sets the name of the provider associated with this location

setSpeed

public void setSpeed (float speedMetersPerSecond)

Set the speed at the time of this location, in meters per second.

setSpeedAccuracyMetersPerSecond

public void setSpeedAccuracyMetersPerSecond (float speedAccuracyMeterPerSecond)

Set the speed accuracy of this location in meters per second.

setTime

public void setTime (long timeMs)

Sets the Unix epoch time of this location fix, in milliseconds since the start of the Unix epoch (00:00:00 January 1 1970 UTC).

setVerticalAccuracyMeters

public void setVerticalAccuracyMeters (float altitudeAccuracyMeters)

Set the altitude accuracy of this location in meters.

toString

public String toString ()

Returns a string representation of the object.

writeToParcel

public void writeToParcel (Parcel parcel, 
                int flags)

Flatten this object in to a Parcel.