Quick Start

This article describes the easiest way to use the HERE Maps API for Java ME to create a mobile mapping application.

Basic Scenario

It only takes a few lines of code to create a fully functioning application with an interactive map. To create an application that displays a map, you need to:

  1. Include the core map library JAR of the Maps API for Java ME as part of the Java build path of your MIDlet.
  2. Set authentication and authorization credentials – this is needed for unlimited access to the Nokia Maps API for Java ME; see also Acquiring Credentials below.
  3. Create a simple MIDlet which instantiates an instance of a MapCanvas passing in the current Display;

Configuring the IDE

When setting up your emulator:

  • Disable user security prompts to avoid being repeatedly asked for permission to use the network.
  • Setup both the emulator and test devices to access the internet and to authenticate/download maps successfully.
Nokia Emulator preferences

Figure 1. Nokia Emulator preferences

When using the API in an application, in order to run it successfully:

  • Ensure that the configuration for the device is CLDC-1.1 and MIDP-2.0. or higher
  • Include the HERE Maps API for Java ME on the classpath.

Figure 2. Netbeans classpath set-up

Nokia IDE for Java ME (Eclipse) Classpath Set-up

  • Under the 'properties' of your project, the maps-core.jar needs to be added as an external JAR under 'Libraries'
  • The JAR needs to be selected as an exported entry under 'Order and Export'.

The maps-core.jar can be found in the ./plugins/maps_api/lib directory of the installed version of the SDK. For example, if you have installed the Nokia Asha SDK 1.0 in C:/Nokia/Devices/Nokia_Asha_SDK_1_0, the maps library JARs will be available in the C:/Nokia/Devices/Nokia_Asha_SDK_1_0/plugins/maps_api/lib directory. For more information about available library JARs, please see Packages and Detection.

Nokia IDE for Java ME (Eclipse) classpath set-up

Figure 3. Nokia IDE for Java ME (Eclipse) classpath set-up

NetBeans Classpath Set-up

  • Under the 'properties' of your project, the maps-core.jar needs to be added as a JAR under 'Libraries & Resources'
  • The JAR needs to be selected as a package entry.

Netbeans classpath set-up

Figure 4. Netbeans classpath set-up

Using Access Credentials

HERE provides several service options for the HERE Maps API for Java ME . Please read the Location API Business Models and Usage Restrictions page to decide which business model best fits your needs.

The service is free to use, but all users must obtain authentication and authorization credentials, which are an app id and a token. To obtain them:

  1. Open HERE Developer Site, in the top-right corner click Sign in, then pick one option:
    • Log in with your HERE account credentials – you may need to create an account first.
    • Log in with your Facebook account credentials.
  2. Open My Apps, click Create App and follow the on-screen instructions.

Setting API Credentials

Having registered and received a set of credentials for your application, set the credentials on the ApplicationContext class included the API. This is usually the first line of code in a real application

The generalized code example below shows how to do this:

// Set up the credentials to use the API:

Please note that the actual values of the strings "YOUR_APPID" and "YOUR_TOKEN" must be the app id and the token you obtain through the registration process.

Displaying a Map

The simplest application that can be created using the HERE Maps API for Java ME is one that displays a pannable, zoomable map. The default map is at minimal zoom and centered over the Gulf of Guinea (0 ° Longitude, 0 ° Latitude) unless the MapDisplayState is also set. To create such an application:

  1. Create a MIDlet class with standard startApp(), destroyApp() and pauseApp() methods.
  2. Update the existing ApplicationContext with your credentials in the startApp() method in order to register the application when retrieving Nokia Maps over the internet.
  3. Obtain a reference to the Display - this is necessary since maps are displayed on a MapCanvas object which in turn requires an instance of the device's Display.
  4. Create the mapCanvas and set the mapCanvas as current. All this code that can be added to the startApp() method.

Below, you can see the outcome of implementing this simple scenario as a map image and also (further down the page) the code showing how it has been achieved.

Street map of Berlin


Figure 5. A basic pannable, zoomable map

public class MapMIDlet extends MIDlet {
	protected void startApp() throws MIDletStateChangeException {
		Display display = Display.getDisplay(this);
		MapCanvas mapCanvas = new MapCanvas(display){
			public void onMapUpdateError(String description, 
				Throwable detail, boolean critical) {
				// Error handling goes here.
			public void onMapContentComplete() {
		    new MapDisplayState(new GeoCoordinate(52.51, 13.4, 0), 10));

Last updated 20 May 2013

Back to top