Package com.esri.arcgisruntime.location

Class LocationDataSource.Location

java.lang.Object

com.esri.arcgisruntime.location.LocationDataSource.Location

Direct Known Subclasses:

NmeaLocationDataSource.NmeaLocation

Enclosing class:

LocationDataSource

public static class LocationDataSource.Location
extends Object

A location update provided by a LocationDataSource, consisting primarily of a Point representing a geographical location, and attributes of location change such as the course (direction of travel), and the velocity (speed of location change).

Also provides information about the accuracy of the location - the possible difference between the true ground location and that reported by the data source from getPosition().

Since:

100.0.0 for Android and 100.9.0 for Java SE

Field Summary

Fields

Modifier and Type	Field	Description
static String	KEY_FLOOR	The key to use with getAdditionalSourceProperties() to retrieve the determined floor used to create the Location object.
static String	KEY_POSITION_SOURCE	The key to use with the Map returned by getAdditionalSourceProperties() to retrieve a String that indicates the source provider of the location.
static String	KEY_SATELLITE_COUNT	The key to use with the Map returned by getAdditionalSourceProperties() to retrieve the number of satellites used to create the Location object.
static String	KEY_TRANSMITTER_COUNT	The key to use with getAdditionalSourceProperties() to retrieve the number of transmitters (iBeacons) used to create the Location object.
static String	POSITION_SOURCE_BLUETOOTH	Value associated with the key KEY_POSITION_SOURCE when location data is acquired from a wireless (Bluetooth) network.
static String	POSITION_SOURCE_CELL	Value associated with the key KEY_POSITION_SOURCE when location data is acquired from a cellular network.
static String	POSITION_SOURCE_GNSS	Value associated with the key KEY_POSITION_SOURCE when location data is acquired from gps.
static String	POSITION_SOURCE_WIFI	Value associated with the key KEY_POSITION_SOURCE when location data is acquired from a wireless local network.

Constructor Summary

Constructors

Constructor	Description
Location(Point position)	Creates a new Location with given Point.
Location(Point position, double horizontalAccuracy, double velocity, double course, boolean lastKnown)	Creates a new Location with given Point, accuracy, velocity, course, and whether the location represents a last known location or not.
Location(Point position, double horizontalAccuracy, double verticalAccuracy, double velocity, double course, boolean lastKnown, Calendar timeStamp)	Creates a new location with the given Point, horizontal accuracy, vertical accuracy, velocity, course, whether the location represents a last known location or not, and timeStamp.
Location(Point position, double horizontalAccuracy, double verticalAccuracy, double velocity, double course, boolean lastKnown, Calendar timeStamp, Map<String,Object> additionalSourceProperties)	Creates a location object with timestamp and additional source properties.

Method Summary

Modifier and Type	Method	Description
Map<String,Object>	getAdditionalSourceProperties()	Gets a set of unmodifiable key-value pairs providing additional meta-data and properties about the source of this LocationDataSource.Location.
double	getCourse()	Returns the course of the location in degrees clockwise, 0 being true North.
double	getHorizontalAccuracy()	Returns the horizontal accuracy of the location in meters.
Point	getPosition()	A Point representing the geographical position of the Location, defined in the spatial reference used by this LocationDataSource.
Calendar	getTimeStamp()	Gets the date and time the location was determined.
double	getVelocity()	Returns the velocity of the location in meters per seconds.
double	getVerticalAccuracy()	Gets the vertical accuracy of the location in meters.
boolean	isLastKnown()	Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

POSITION_SOURCE_GNSS

public static final String POSITION_SOURCE_GNSS

Value associated with the key KEY_POSITION_SOURCE when location data is acquired from gps.

Since:

100.10.0

See Also:

getAdditionalSourceProperties(), Constant Field Values

POSITION_SOURCE_WIFI

public static final String POSITION_SOURCE_WIFI

Value associated with the key KEY_POSITION_SOURCE when location data is acquired from a wireless local network.

Since:

100.10.0

See Also:

getAdditionalSourceProperties(), Constant Field Values

POSITION_SOURCE_CELL

public static final String POSITION_SOURCE_CELL

Value associated with the key KEY_POSITION_SOURCE when location data is acquired from a cellular network.

Since:

100.10.0

See Also:

getAdditionalSourceProperties(), Constant Field Values

POSITION_SOURCE_BLUETOOTH

public static final String POSITION_SOURCE_BLUETOOTH

Value associated with the key KEY_POSITION_SOURCE when location data is acquired from a wireless (Bluetooth) network.

Since:

100.14.0

See Also:

getAdditionalSourceProperties(), Constant Field Values

KEY_POSITION_SOURCE

public static final String KEY_POSITION_SOURCE

The key to use with the Map returned by getAdditionalSourceProperties() to retrieve a String that indicates the source provider of the location. If the key is present in the Map, the associated value will be one of:

• POSITION_SOURCE_GNSS. GNSS indicates global navigation satellite system.
• POSITION_SOURCE_WIFI
• POSITION_SOURCE_CELL
• POSITION_SOURCE_BLUETOOTH

It is possible to have multiple position sources. In that case, the associated value of KEY_POSITION_SOURCE is a concatenated String of comma-separated values.

Since:

100.10.0

KEY_SATELLITE_COUNT

public static final String KEY_SATELLITE_COUNT

The key to use with the Map returned by getAdditionalSourceProperties() to retrieve the number of satellites used to create the Location object.

Since:

100.10.0

KEY_FLOOR

public static final String KEY_FLOOR

The key to use with getAdditionalSourceProperties() to retrieve the determined floor used to create the Location object.

Since:

100.14.0

KEY_TRANSMITTER_COUNT

public static final String KEY_TRANSMITTER_COUNT

The key to use with getAdditionalSourceProperties() to retrieve the number of transmitters (iBeacons) used to create the Location object.

Since:

100.14.0

Constructor Detail

Location

public Location(Point position)

Creates a new Location with given Point. Other properties will have default values.

Parameters:

position - a Point object representing the geographical position of the new Location

Throws:

IllegalArgumentException - if position is null or the spatial reference of position is null

Since:

100.0.0 for Android and 100.9.0 for Java SE

Location

public Location(Point position,
                double horizontalAccuracy,
                double velocity,
                double course,
                boolean lastKnown)

Creates a new Location with given Point, accuracy, velocity, course, and whether the location represents a last known location or not.

Parameters:

position - a Point object representing the geographical position of the new Location

horizontalAccuracy - the horizontal accuracy of the new location

velocity - the current speed of the locations movement

course - the current direction of the locations movement

lastKnown - Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location. True if the location represents a last known position; false if the position information is current. Setting this to true will render with the LocationDisplay.getAcquiringSymbol(), typically a grayed out location symbol.

Throws:

IllegalArgumentException - if position is null or the spatial reference of position is null

Since:

100.0.0 for Android and 100.9.0 for Java SE

Location

public Location(Point position,
                double horizontalAccuracy,
                double verticalAccuracy,
                double velocity,
                double course,
                boolean lastKnown,
                Calendar timeStamp)

Creates a new location with the given Point, horizontal accuracy, vertical accuracy, velocity, course, whether the location represents a last known location or not, and timeStamp.

Parameters:

position - a Point object representing the geographical position of the new Location

horizontalAccuracy - the horizontal accuracy in meters

verticalAccuracy - the vertical accuracy in meters

velocity - the current speed of the locations movement in meters per second

course - the location's course in degrees (clockwise), 0 being true North

lastKnown - Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location. True if the location represents a last known position; false if the position information is current. Setting this to true will render with the LocationDisplay.getAcquiringSymbol(), typically a grayed out location symbol.

timeStamp - the date and time the location was determined

Throws:

IllegalArgumentException - if position is null or the spatial reference of position is null

Since:

100.4.0 for Android and 100.9.0 for Java SE

Location

public Location(Point position,
                double horizontalAccuracy,
                double verticalAccuracy,
                double velocity,
                double course,
                boolean lastKnown,
                Calendar timeStamp,
                Map<String,Object> additionalSourceProperties)

Creates a location object with timestamp and additional source properties.

A Location can be created from a variety of sources and using different technologies. By supplying additionalSourceProperties you can allow users of this Location to find out how the data was captured. Information should be provided to {additionalSourceProperties} as a set of key-value pairs, where the String key describes the type of data held in the Object value. Values MUST be basic data types such as string, floating point, integer, boolean or date. You can use any string for the key — but the ArcGIS Runtime API recognizes a number of well known keys, which include:

• "satelliteCount" key; use KEY_SATELLITE_COUNT. Associated value, an integer, is the number of satellites used to fix the Location.
• "positionSource" key; use KEY_POSITION_SOURCE. Associated value, a String, can be: POSITION_SOURCE_GNSS, POSITION_SOURCE_WIFI, POSITION_SOURCE_CELL, or POSITION_SOURCE_BLUETOOTH. (GNSS indicates global navigation satellite system.) It is possible to have multiple position sources. In that case, the associated value of KEY_POSITION_SOURCE is a concatenated String of comma-separated values.
• "transmitterCount" key; use KEY_TRANSMITTER_COUNT. The number of transmitters used to fix the Location.
• "floor" key; use KEY_FLOOR. The floor used to fix the Location.

Keys are case-sensitive.

Parameters:

position - a Point object representing the geographical position of the new Location

horizontalAccuracy - the horizontal accuracy in meters

verticalAccuracy - the vertical accuracy in meters

velocity - the current speed of the locations movement in meters per second

course - the location's course in degrees (clockwise), 0 being true North

lastKnown - Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location. True if the location represents a last known position; false if the position information is current. Setting this to true will render with the LocationDisplay.getAcquiringSymbol(), typically a grayed out location symbol.

timeStamp - a timestamp when location was received. Can be null

additionalSourceProperties - a set of key-value pairs providing additional meta-data and properties about the source of this Location

Throws:

IllegalArgumentException - if position is null or the spatial reference of position is null

IllegalArgumentException - if additionalSourceProperties is null

Since:

100.10.0

See Also:

getAdditionalSourceProperties(), KEY_SATELLITE_COUNT, KEY_POSITION_SOURCE

Method Detail

getAdditionalSourceProperties

public Map<String,Object> getAdditionalSourceProperties()

Gets a set of unmodifiable key-value pairs providing additional meta-data and properties about the source of this LocationDataSource.Location.

A Location object can be created manually or by a variety of LocationDataSource types - for example from the default platform data source or external GPS. When user code receives a new Location, it can be important to determine how the information was obtained.

In addition, mobile devices may provide different details about their in-built location services. For example, Android systems can provide data on the number of satellites used to find a position. When a given property is not available to the data source, the entry will be omitted from the additionalSourceProperties.

These additionalSourceProperties() provide a means for the creator of a Location object to record flexible information such as:

• The confidence level associated with the location.
• The method used to obtain the location.
• The provenance of the location.

Information is provided as a set of key-value pairs, where the String key describes the type of data held in the Object value. Values MUST be basic data types such as string, numeric, boolean or date. The creator of the Location can use any string for the key - but the Runtime SDK recognizes a number of well known keys, which include:

• "satelliteCount" key; use KEY_SATELLITE_COUNT. Associated value, an integer, is the number of satellites used to fix the Location.
• "positionSource" key; use KEY_POSITION_SOURCE. Associated value, a String, can be: POSITION_SOURCE_GNSS, POSITION_SOURCE_WIFI, POSITION_SOURCE_CELL, or POSITION_SOURCE_BLUETOOTH. (GNSS indicates global navigation satellite system.) It is possible to have multiple position sources. In that case, the associated value of KEY_POSITION_SOURCE is a concatenated String of comma-separated values.
• "transmitterCount" key; use KEY_TRANSMITTER_COUNT. The number of transmitters used to fix the Location.
• "floor" key; use KEY_FLOOR. The floor used to fix the Location.

Keys are case-sensitive.

Returns:

a set of key-value pairs providing additional meta-data and properties about the source of this Location

Since:

100.10.0

getTimeStamp

public Calendar getTimeStamp()

Gets the date and time the location was determined.

Returns:

a Calendar object representing the time the location was determined

Since:

100.4.0 for Android and 100.9.0 for Java SE

getCourse

public double getCourse()

Returns the course of the location in degrees clockwise, 0 being true North.

Returns:

a double value representing the direction the device is moving, in degrees clockwise from north

Since:

100.0.0 for Android and 100.9.0 for Java SE

getHorizontalAccuracy

public double getHorizontalAccuracy()

Returns the horizontal accuracy of the location in meters.

Returns:

the accuracy of the reported location, in meters

Since:

100.0.0 for Android and 100.9.0 for Java SE

getVerticalAccuracy

public double getVerticalAccuracy()

Gets the vertical accuracy of the location in meters.

Returns:

the vertical accuracy of the location in meters, Double.NaN if no vertical accuracy is available for the location.

Since:

100.3.0

getVelocity

public double getVelocity()

Returns the velocity of the location in meters per seconds. Default value is 0.0.

Returns:

the current speed of the locations movement

Since:

100.0.0 for Android and 100.9.0 for Java SE

getPosition

public Point getPosition()

A Point representing the geographical position of the Location, defined in the spatial reference used by this LocationDataSource.

You can find out which spatial reference is used by calling getPosition().

Returns:

the geographical position of the Location

Since:

100.0.0 for Android and 100.9.0 for Java SE

isLastKnown

public boolean isLastKnown()

Indicates whether this is an outdated position retrieved and cached earlier (last known position) and therefore not guaranteed to represent the current location. True if the location represents a last known position; false if the position information is current. Default value is false if this object was created by the Location(Point) constructor.

For many types of location provider, it may take a while to receive the first location update. Last known locations can provide a suitable surrogate until current location information can be retrieved.

Returns:

true if this location represents a last known position; false if the location is current

Since:

100.0.0 for Android and 100.9.0 for Java SE