LocationCompat

Added in 1.6.0

public final class LocationCompat


Helper for accessing features in android.location.Location.

Summary

Constants

static final String
EXTRA_BEARING_ACCURACY = "bearingAccuracy"

Constant used as a key to store bearing accuracy in getExtras for Android SDK levels below Oreo (26).

static final String
EXTRA_IS_MOCK = "mockLocation"

Constant used as a key to store mock location status in getExtras for Android SDK levels below JBMR2 (18).

static final String
EXTRA_MSL_ALTITUDE = "androidx.core.location.extra.MSL_ALTITUDE"

Constant used as a key to store Mean Sea Level altitude in getExtras.

static final String
EXTRA_MSL_ALTITUDE_ACCURACY = "androidx.core.location.extra.MSL_ALTITUDE_ACCURACY"

Constant used as a key to store Mean Sea Level altitude in getExtras.

static final String
EXTRA_SPEED_ACCURACY = "speedAccuracy"

Constant used as a key to store speed accuracy in getExtras for Android SDK levels below Oreo (26).

static final String
EXTRA_VERTICAL_ACCURACY = "verticalAccuracy"

Constant used as a key to store vertical accuracy in getExtras for Android SDK levels below Oreo (26).

Public methods

static float

Get the estimated bearing accuracy of this location in degrees.

static long

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

static long

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

static @FloatRange(from = 0.0) float

Returns the estimated Mean Sea Level altitude accuracy in meters of the location at the 68th percentile confidence level.

static double

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

static float

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

static float

Get the estimated vertical accuracy of this location in meters.

static boolean

Returns true if this location has a bearing accuracy.

static boolean

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

static boolean

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

static boolean

Returns true if this location has a speed accuracy.

static boolean

Returns true if this location has a vertical accuracy.

static boolean
isMock(@NonNull Location location)

Returns true if this location is marked as a mock location.

static void

Removes the bearing accuracy from the location.

static void

Removes the Mean Sea Level altitude from the location.

static void

Removes the Mean Sea Level altitude accuracy from the location.

static void

Removes the speed accuracy from the location.

static void

Removes the vertical accuracy from the location.

static void
setBearingAccuracyDegrees(
    @NonNull Location location,
    float bearingAccuracyD
)

Set the estimated bearing accuracy of this location in degrees.

static void
setMock(@NonNull Location location, boolean mock)

Sets whether this location is marked as a mock location.

static void
setMslAltitudeAccuracyMeters(
    @NonNull Location location,
    @FloatRange(from = 0.0) float mslAltitudeAccuracyMeters
)

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

static void
setMslAltitudeMeters(
    @NonNull Location location,
    double mslAltitudeMeters
)

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

static void
setSpeedAccuracyMetersPerSecond(
    @NonNull Location location,
    float speedAccuracyMps
)

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

static void
setVerticalAccuracyMeters(
    @NonNull Location location,
    float verticalAccuracyM
)

Set the estimated vertical accuracy of this location in meters.

Constants

EXTRA_BEARING_ACCURACY

Added in 1.7.0
public static final String EXTRA_BEARING_ACCURACY = "bearingAccuracy"

Constant used as a key to store bearing accuracy in getExtras for Android SDK levels below Oreo (26).

EXTRA_IS_MOCK

Added in 1.7.0
public static final String EXTRA_IS_MOCK = "mockLocation"

Constant used as a key to store mock location status in getExtras for Android SDK levels below JBMR2 (18).

EXTRA_MSL_ALTITUDE

Added in 1.9.0
public static final String EXTRA_MSL_ALTITUDE = "androidx.core.location.extra.MSL_ALTITUDE"

Constant used as a key to store Mean Sea Level altitude in getExtras.

EXTRA_MSL_ALTITUDE_ACCURACY

Added in 1.9.0
public static final String EXTRA_MSL_ALTITUDE_ACCURACY = "androidx.core.location.extra.MSL_ALTITUDE_ACCURACY"

Constant used as a key to store Mean Sea Level altitude in getExtras.

EXTRA_SPEED_ACCURACY

Added in 1.7.0
public static final String EXTRA_SPEED_ACCURACY = "speedAccuracy"

Constant used as a key to store speed accuracy in getExtras for Android SDK levels below Oreo (26).

EXTRA_VERTICAL_ACCURACY

Added in 1.7.0
public static final String EXTRA_VERTICAL_ACCURACY = "verticalAccuracy"

Constant used as a key to store vertical accuracy in getExtras for Android SDK levels below Oreo (26).

Public methods

getBearingAccuracyDegrees

Added in 1.7.0
public static float getBearingAccuracyDegrees(@NonNull Location location)

Get the estimated bearing accuracy of this location in degrees.

NOTE: On API levels below 26, the concept of bearing accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to read a float extra with the key EXTRA_BEARING_ACCURACY and return the result.

getElapsedRealtimeMillis

Added in 1.6.0
public static long getElapsedRealtimeMillis(@NonNull Location location)

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

getElapsedRealtimeNanos

Added in 1.6.0
public static long getElapsedRealtimeNanos(@NonNull Location location)

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

This value can be reliably compared to SystemClock.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.

NOTE: On API levels below 17, this method will attempt to provide an elapsed realtime based on the difference between system time and the location time. This should be taken as a best "guess" at what the elapsed realtime might have been, but if the clock used for location derivation is different from the system clock, the results may be inaccurate.

getMslAltitudeAccuracyMeters

Added in 1.9.0
public static @FloatRange(from = 0.0) float getMslAltitudeAccuracyMeters(@NonNull Location location)

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

This is only valid if hasMslAltitudeAccuracy is true.

NOTE: On API levels below 34, the concept of Mean Sea Level altitude accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to read a float extra with the key EXTRA_MSL_ALTITUDE_ACCURACY and return the result.

getMslAltitudeMeters

Added in 1.9.0
public static double getMslAltitudeMeters(@NonNull Location location)

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

This is only valid if hasMslAltitude is true.

NOTE: On API levels below 34, the concept of Mean Sea Level altitude does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to read a double extra with the key EXTRA_MSL_ALTITUDE and return the result.

getSpeedAccuracyMetersPerSecond

Added in 1.7.0
public static float getSpeedAccuracyMetersPerSecond(@NonNull Location location)

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

NOTE: On API levels below 26, the concept of speed accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to read a float extra with the key EXTRA_SPEED_ACCURACY and return the result.

getVerticalAccuracyMeters

Added in 1.7.0
public static float getVerticalAccuracyMeters(@NonNull Location location)

Get the estimated vertical accuracy of this location in meters.

NOTE: On API levels below 26, the concept of vertical accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to read a float extra with the key EXTRA_VERTICAL_ACCURACY and return the result.

hasBearingAccuracy

Added in 1.7.0
public static boolean hasBearingAccuracy(@NonNull Location location)

Returns true if this location has a bearing accuracy.

hasMslAltitude

Added in 1.9.0
public static boolean hasMslAltitude(@NonNull Location location)

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

NOTE: On API levels below 34, the concept of Mean Sea Level altitude does not exist. In order to allow for backwards compatibility and testing however, this method will return true if an extra value is with the key EXTRA_MSL_ALTITUDE.

See also
hasMslAltitude

hasMslAltitudeAccuracy

Added in 1.9.0
public static boolean hasMslAltitudeAccuracy(@NonNull Location location)

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

NOTE: On API levels below 34, the concept of Mean Sea Level altitude accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will return true if an extra value is with the key EXTRA_MSL_ALTITUDE_ACCURACY.

hasSpeedAccuracy

Added in 1.7.0
public static boolean hasSpeedAccuracy(@NonNull Location location)

Returns true if this location has a speed accuracy.

See also
hasSpeedAccuracy

hasVerticalAccuracy

Added in 1.7.0
public static boolean hasVerticalAccuracy(@NonNull Location location)

Returns true if this location has a vertical accuracy.

isMock

Added in 1.6.0
public static boolean isMock(@NonNull Location location)

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.

NOTE: On API levels below 18, the concept of a mock location does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to read a boolean extra with the key EXTRA_IS_MOCK and use the result to determine whether this should be considered a mock location.

See also
LocationManager

removeBearingAccuracy

Added in 1.12.0
public static void removeBearingAccuracy(@NonNull Location location)

Removes the bearing accuracy from the location.

removeMslAltitude

Added in 1.9.0
public static void removeMslAltitude(@NonNull Location location)

Removes the Mean Sea Level altitude from the location.

NOTE: On API levels below 34, the concept of Mean Sea Level altitude does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to remove any extra value with the key EXTRA_MSL_ALTITUDE.

removeMslAltitudeAccuracy

Added in 1.9.0
public static void removeMslAltitudeAccuracy(@NonNull Location location)

Removes the Mean Sea Level altitude accuracy from the location.

NOTE: On API levels below 34, the concept of Mean Sea Level altitude accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to remove any extra value with the key EXTRA_MSL_ALTITUDE_ACCURACY.

removeSpeedAccuracy

Added in 1.12.0
public static void removeSpeedAccuracy(@NonNull Location location)

Removes the speed accuracy from the location.

removeVerticalAccuracy

Added in 1.12.0
public static void removeVerticalAccuracy(@NonNull Location location)

Removes the vertical accuracy from the location.

setBearingAccuracyDegrees

Added in 1.7.0
public static void setBearingAccuracyDegrees(
    @NonNull Location location,
    float bearingAccuracyD
)

Set the estimated bearing accuracy of this location in degrees.

NOTE: On API levels below 26, the concept of bearing accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to set a float extra with the key EXTRA_BEARING_ACCURACY to include bearing accuracy. Be aware that this will overwrite any prior extra value under the same key.

setMock

Added in 1.6.0
public static void setMock(@NonNull Location location, boolean mock)

Sets whether this location is marked as a mock location.

NOTE: On API levels below 18, the concept of a mock location does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to set a boolean extra with the key EXTRA_IS_MOCK to mark the location as mock. Be aware that this will overwrite any prior extra value under the same key.

setMslAltitudeAccuracyMeters

Added in 1.9.0
public static void setMslAltitudeAccuracyMeters(
    @NonNull Location location,
    @FloatRange(from = 0.0) float mslAltitudeAccuracyMeters
)

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

NOTE: On API levels below 34, the concept of Mean Sea Level altitude accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to set a float extra with the key EXTRA_MSL_ALTITUDE_ACCURACY to include Mean Sea Level altitude accuracy. Be aware that this will overwrite any prior extra value under the same key.

setMslAltitudeMeters

Added in 1.9.0
public static void setMslAltitudeMeters(
    @NonNull Location location,
    double mslAltitudeMeters
)

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

NOTE: On API levels below 34, the concept of Mean Sea Level altitude does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to set a double extra with the key EXTRA_MSL_ALTITUDE to include Mean Sea Level altitude. Be aware that this will overwrite any prior extra value under the same key.

setSpeedAccuracyMetersPerSecond

Added in 1.7.0
public static void setSpeedAccuracyMetersPerSecond(
    @NonNull Location location,
    float speedAccuracyMps
)

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

NOTE: On API levels below 26, the concept of speed accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to set a float extra with the key EXTRA_SPEED_ACCURACY to include speed accuracy. Be aware that this will overwrite any prior extra value under the same key.

setVerticalAccuracyMeters

Added in 1.7.0
public static void setVerticalAccuracyMeters(
    @NonNull Location location,
    float verticalAccuracyM
)

Set the estimated vertical accuracy of this location in meters.

NOTE: On API levels below 26, the concept of vertical accuracy does not exist. In order to allow for backwards compatibility and testing however, this method will attempt to set a float extra with the key EXTRA_VERTICAL_ACCURACY to include vertical accuracy. Be aware that this will overwrite any prior extra value under the same key.