Using the Location API

The Location API is defined in the javax.microedition.location package. The API's presence can be discovered by using the system property microedition.location.version. The value of this system property is the version of the implemented API specification, for example, "1.0". This section of the developer's guide will demonstrate the usage of the Location API with code samples from an example MIDlet called Tourist Route available at Forum Nokia and also included in this developer's guide. Each example code snippet shows only the essential part of the Location API usage. While reading this document it might also be useful to take a look at the TouristRoute MIDlet's source code in the IDE.

All the Location API classes are within the same package. This section introduces the API classes in small functionality groups, which should help to get the pieces together. The first operation in the API use is choosing the location provider; therefore, those classes are introduced first in the table below.

**Table 19:** Classes needed in choosing the location provider
Class	Short definition
`Criteria`	Used for the selection of the location provider.
`LocationProvider`	Represents a source of the location information (e.g., GPS module).

Usually an application that uses the Location API examines the device's position updates. The Location API uses listeners to examine these updates. The table below introduces these listeners.

**Table 20:** Listeners in the Location API
Class	Short definition
`LocationListener`	Listener that receives events associated with a particular `LocationProvider`.
`ProximityListener`	Listener to events associated with detecting proximity to registered coordinates.

The table below briefly introduces a set of classes for the measurement of a device's location.

**Table 21:** Classes needed in the device's location measurement
Class	Short definition
`AddressInfo`	Holds textual address information about a location.
`Coordinates`	Represents coordinates as latitude-longitude-altitude values.
`Location`	Represents the standard set of location information (time-stamped coordinates, speed, accuracy, course, etc.)
`LocationException`	Is thrown when a location API-specific error has occurred.
`QualifiedCoordinates`	Represents coordinates as latitude-longitude-altitude values that are associated with an accuracy value.

Location information can be stored for later use in the landmark store. The table below introduces the Location API classes for this purpose.

**Table 22:** Landmark and landmark store classes
Class	Short definition
`Landmark`	Represents a known location with a name.
`LandmarkException`	Is thrown when an error related to handling landmarks has occurred.
`LandmarkStore`	Methods for persistent landmark store management (store, delete, and retrieve landmarks).

If the device's sensors support the obtaining of orientation information, the information is available through the Location API's Orientation class (see the table below).

**Table 23:** Orientation information class in the Location API
Class	Short definition
`Orientation`	Represents the physical orientation of the device.