Package javax.microedition.location

The javax.microedition.location package contains the basic classes needed to request and get a location result.


Interface Summary
LocationListener The LocationListener represents a listener that receives events associated with a particular LocationProvider.
ProximityListener This interface represents a listener to events associated with detecting proximity to some registered coordinates.

Class Summary
AddressInfo The AddressInfo class holds textual address information about a location.
Coordinates The Coordinates class represents coordinates as latitude-longitude-altitude values.
Criteria The criteria used for the selection of the location provider is defined by the values in this class.
Landmark The Landmark class represents a landmark, i.e. a known location with a name.
LandmarkStore The LandmarkStore class provides methods to store, delete and retrieve landmarks from a persistent landmark store.
Location The Location class represents the standard set of basic location information.
LocationProvider This is the starting point for applications using this API and represents a source of the location information.
Orientation The Orientation class represents the physical orientation of the terminal.
QualifiedCoordinates The QualifiedCoordinates class represents coordinates as latitude-longitude-altitude values that are associated with an accuracy value.

Exception Summary
LandmarkException The LandmarkException is thrown when an error related to handling landmarks has occurred.
LocationException The LocationException is thrown when a location API specific error has occurred.

Package javax.microedition.location Description

The javax.microedition.location package contains the basic classes needed to request and get a location result.

The LocationProvider class represents a module that is able to determine the location of the terminal. This may be implemented using any possible location methods, for example, satellite based methods like GPS, cellular network based methods, short-range positioning methods like Bluetooth Local Positioning, etc. The implementation may also combine the methods in various ways to get the optimal result.

The application can specify criteria for selecting the location provider and obtain a LocationProvider instance that is able to fulfil these criteria as closely as possible. By using the LocationProvider, the application can get Location objects representing the location of the terminal at the time of the measurement. The application can either request a single Location object or be periodically updated with new Location objects via a LocationListener implemented by the application.

The location is represented by the Location object that contains a QualifiedCoordinates object representing the geographical coordinates (latitude, longitude and altitude) and information about their accuracy, a timestamp and possibly information about speed and course of the terminal. For some location methods, the Location object may also contain an AddressInfo object that includes textual address information, e.g. a street address.

The Location gives the accuracy of the coordinates as the radius of a circular area indicating the 1-sigma confidence level. The 1-sigma confidence refers to the standard deviation of the distribution. Assuming a normal distribution (which is not necessarily the case), this implies that the actual location is within the circle defined by the returned point and radius at a probability of approximately 68%. The actual location may thus be also outside of the circle, which has to be taken into account when using the location information in applications.

This package also includes a database of landmarks. A landmark is a known physical location that is associated with a name representing that location for the end user. The user can store commonly used locations in the database. Examples of landmarks could be e.g. the user's home, office, etc. The landmark database must be shared between all Java applications and may be shared with other applications in the terminal, including native applications, so that the end user has a consistent user experience across all location based applications on the terminal.

Mandatory and optional features

This API contains some options whose availability depends on the used location methods. These features are not optional in order to allow for differences in the implementations and to cause unnecessary fragmentation, but they are unavoidable due to the differences in the underlying location methods. Implementations should support all features that are possible with the locations methods that are used.

Mandatory features for all location methods are:

Mandatory other API features for the terminal are:

Features whose availability depend on the used location method:

Optional features whose availability depend on the landmark store implementation of the terminal and its possible relation to landmark stores shared with native applications:

Additionally, depending on the hardware capabilities of the terminal, the following features are optionally supported:

In general, every implementation MUST contain all the classes, interfaces and methods as defined in this specification. Those features that are optional to implement have a defined behaviour in the case the feature is not supported by the implementation.

Security of this API

Some methods in this API are defined to throw a SecurityException if the caller does not have the permissions needed to perform the action. This MUST be enforced by an appropriate security framework in the platform.

Using the MIDP 2.0 Security Framework

If this API is implemented on the MIDP 2.0 platform, the security framework of MIDP 2.0 MUST be used as defined below.

The table below defines the names of the permissions used and the methods that are protected by each permission. The definition of the policy for these permissions is out of scope for this specification.

Permission name

Methods protected by this permission


LocationProvider.getLocation(), LocationProvider.setLocationListener(), LocationProvider.getLastKnownLocation()





LandmarkStore.getInstance(), LandmarkStore.listLandmarkStores()


LandmarkStore.addLandmark(), LandmarkStore.deleteLandmark(), LandmarkStore.removeLandmarkFromCategory(), LandmarkStore.updateLandmark()


LandmarkStore.addCategory(), LandmarkStore.deleteCategory()

LandmarkStore.createLandmarkStore(), LandmarkStore.deleteLandmarkStore()

Identification of the Location API

To enable applications to test for the presence of the Location API and its version during runtime, a system property is defined. Platforms where this API is implemented according to this specification shall include a system property with a key "microedition.location.version". When System.getProperty is called with this key, implementations conforming to this specification shall return the version string "1.0". (Note: although the specification version number for this Maintenance Release contains three digits, this system property includes only the two-digit major.minor part of it, because the difference is so small that it should not be significant for applications. If a later release of this specification contains such changes that are relevant for applications then the major and/or minor digit of the version number will be changed.).

Example of Usage

The following piece of code illustrates how to obtain the current location of the terminal. This piece of code illustrates obtaining the location syncronously. An application would normally perform this within a separate thread, because the getLocation method may block for a long time.

try {

    // Create a Criteria object for defining desired selection criteria
    Criteria cr = new Criteria();
    // Specify horizontal accuracy of 500 meters, leave other parameters 
    // at default values.
    LocationProvider lp = LocationProvider.getInstance(cr);

    // get the location, one minute timeout
    Location l = lp.getLocation(60);

    Coordinates c = l.getQualifiedCoordinates();
    if (c != null) {
       // use coordinate information
} catch (LocationException e) {
   // not able to retrive location information

The following example illustrates how to use the LocationListener for subscribing to periodic location updates. This example creates a handler thread to handle the updates so that the methods on the listener would not block the platform implementation threads for a long time.

class MovementTracker implements LocationListener {
    float movementDistance;
    LocationProvider provider;
    Location lastValidLocation;
    UpdateHandler handler;
    boolean done;

    public MovementTracker(float movementDistance) throws LocationException {
	this.movementDistance = movementDistance;
	done = false;
	handler = new UpdateHandler();
	new Thread(handler).start();
	provider = LocationProvider.getInstance(null);
	provider.setLocationListener(this, -1, -1, -1);

    public void locationUpdated(LocationProvider provider, Location location) {

    public void providerStateChanged(LocationProvider provider, int newState) {

    class UpdateHandler implements Runnable {
	private Location updatedLocation = null;

	// The run method performs the actual processing of the location 
	// updates
	public void run() {
	    Location locationToBeHandled = null;
	    while (!done) {
		synchronized(this) {
		    if (updatedLocation == null) {
			try {
			} catch (Exception e) {
			    // Handle interruption
		    locationToBeHandled = updatedLocation;
		    updatedLocation = null;

		// The benefit of the MessageListener is here.
		// This thread could via similar triggers be
		// handling other kind of events as well in
		// addition to just receiving the location updates.
		if (locationToBeHandled != null) 

	public synchronized void handleUpdate(Location update) {
	    updatedLocation = update;

	private void processUpdate(Location update) {
	    if ( update.getQualifiedCoordinates().distance(
			lastValidLocation.getQualifiedCoordinates() ) 
		 > movementDistance ) {
		// Alert user to movement...
		// Cache new position as we have moved a sufficient distance 
		// from last one
		lastValidLocation = location;

LAPI 1.0

Copyright © 2003-2005 Nokia Corporation. All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.