Android
android.location
public class

android.location.Location

java.lang.Object
android.location.Location Parcelable

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

      Value  
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.  0x00000000 
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).  0x00000001 
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).  0x00000002 
Constants inherited 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    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'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.
          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 the receiver.
          void  writeToParcel(Parcel parcel, int flags)
Flatten this object in to a Parcel.
Methods inherited from class java.lang.Object
Methods inherited from interface android.os.Parcelable

Details

Constants

public static final Creator<Location> CREATOR

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)

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)

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)

Public Constructors

public Location(String provider)

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)

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

Public Methods

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.

Parameters

dest the destination location

Returns

  • the initial bearing in degrees

public static 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.

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

Throws

NullPointerException if coordinate is null
IllegalArgumentException if the coordinate is not in one of the valid formats.

public int describeContents()

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

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

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)

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 float getAccuracy()

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

public double getAltitude()

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

public float getBearing()

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

public 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

public double getLatitude()

Returns the latitude of this fix.

public double getLongitude()

Returns the longitude of this fix.

public String getProvider()

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

public float getSpeed()

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

public long getTime()

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

public boolean hasAccuracy()

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

public boolean hasAltitude()

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

public boolean hasBearing()

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

public boolean hasSpeed()

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

public void removeAccuracy()

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

public void removeAltitude()

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

public void removeBearing()

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

public void removeSpeed()

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

public void reset()

Clears the contents of the location.

public void set(Location l)

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

public void setAccuracy(float accuracy)

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

public void setAltitude(double altitude)

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

public void setBearing(float bearing)

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

public void setExtras(Bundle extras)

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

public void setLatitude(double latitude)

Sets the latitude of this fix.

public void setLongitude(double longitude)

Sets the longitude of this fix.

public void setProvider(String provider)

Sets the name of the provider that generated this fix.

public void setSpeed(float speed)

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

public void setTime(long time)

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

public String toString()

Returns a string containing a concise, human-readable description of the receiver.

Returns

  • String a printable representation for the receiver.

public void writeToParcel(Parcel parcel, int flags)

Flatten this object in to a Parcel.
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:56