Displaying maps on screen

Acquiring API credentials

Maps API invokes an authentication service when accessing maps online. Although it is possible to obtain access without acquiring authentication credentials, such access may be restricted or of inferior performance. In order to get the full potential out of the API, you must get credentials that authenticate your application against the Services. Please read through the Location API Business Models and Usage Restrictions page, so that you can decide which business model fits your needs best. The authentication itself requires your unique Maps API credentials, namely AppId and Token. You can get these credentials from the API Registration page at Nokia Developer.

Using API credentials

After registering your application, you must set the following credentials in the ApplicationContext class:

ApplicationContext.getInstance().setAppID(...);
ApplicationContext.getInstance().setToken(...);

Basic map

The following code , when added to a MIDlet, displays a basic map of the world. The map centers on Rome, Italy. You can pan/zoom the map by default.

Display display = Display.getDisplay(this);
CustomMapCanvas canvas = new CustomMapCanvas(display);
MapDisplay mapDisplay = canvas.getMapDisplay();
//Gets the coordinates for Rome, Italy
GeoCoordinate geo = new GeoCoordinate(41.90311, 12.49576, 0.0f);
//Sets the center of the map to the given coordinates
mapDisplay.setCenter(geo);

display.setCurrent(canvas);

where CustomMapCanvas is a concrete class implementation that extends the abstract MapCanvas:

import javax.microedition.lcdui.Display;

import com.nokia.maps.map.MapCanvas;

public class CustomMapCanvas extends MapCanvas {

      public CustomMapCanvas(Display display) {
            super(display);
            // TODO Auto-generated constructor stub
      }

      public void onMapContentComplete() {
            // TODO Auto-generated method stub
      }

      public void onMapUpdateError(String arg0, Throwable arg1, boolean arg2) {
            // TODO Auto-generated method stub  
      }     
}

Drawing objects on the map

The Maps API can draw a variety of shapes such as circles, rectangles and polylines over a map. Two types of markers are supported. You can either use the predefined standard markers or include your own image resources with your application and use custom markers.

The following example shows how to add a MapStandardMarker:

MapStandardMarker marker = canvas.getMapFactory().createStandardMarker(
    geo, 10, null, MapStandardMarker.BALLOON); 
mapDisplay.addMapObject(marker);

Accessing online services

The Maps API provides access to online services such as search and routing. Search is able to specify a GeoCoordinate for an address or vice versa, and can retrieve a list of points of interest nearby. It can also be queried for more details about a point of interest. The routing service may be used to find a way to travel between two or more GeoCoordinates. For further details on how to use these services please check the routing and search examples.