Maps API

This part of the guide defines the NokiaMaps API for Java ME, explains its purpose, summarizes its features and outlines how it supports third-party application development.

What Is the Maps API for Java ME?

The Nokia Maps API for Java ME is a set of programming interfaces that enable developers to build mobile device applications based on Nokia Maps. The API provides mapping, search and routing functionality and targets devices that support the Mobile Information Device Profile (MIDP) for Java Micro Edition, such as Nokia Series 40 devices.

The simplest map you can create with this API is a zoomable and pannable map that uses default settings. You can change its look and behavior, and add overlays with custom content. Through custom MapComponents, the API allows you to implement handling for touch and keypress events, which in turn allows users to interact with the displayed content.

Feature List

The main features offered by the Maps API for Java ME are summarized in the table below:

**Table:** Main features of the Nokia Maps API for Java ME
Feature	Description
Maps	Display maps of any location in the world and in satellite, terrain and hybrid. You can enrich the map with custom content such as Markers and Polylines.
Searches	With the help of the places search service, the API supports local search and places look-up by category; use this functionality to find places matching a given free text such as 'restaurant' in a defined area. Your application receives (and can display) detailed information about relevant places, including contact details, opening times and reviews.
Geocoding/Reverse Geocoding	The API's built-in search manager generates location-based search results, using text search criteria. Provide a street address to obtain the geographic coordinates, or retrieve an address by supplying the geo coordinates as input for the search.
Routing	The routing service gives your application the ability to calculate and render routes between any start and end point, taking into consideration transport and traffic preferences.
Custom items	The API allows you to add standard markers or create custom ones, using any `Image` resource. You can also add geo shapes based on coordinates to the map: polygons, polylines, circles or rectangles. Through the use of `MapComponents` you can make these custom map object interactive.
Touch Support	The API allows the end user to pan and zoom the map using touch by default. It is also possible for a developer to extend the basic touch support through creating `MapComponents` which respond directly to touch events.
Sharing	Build a location sharing facility into your app. Let your users send map images to one another. The API includes integration with other Nokia products offering a mechanism to embed a location URL in an SMS message, where the receiving user can view the location on the map.
KML	Integrate KML assets from other sources - parse and import previously created geospatial data and show the content on the map without having to recreate it manually.

Device Compatibility

This API is designed to work with any devices supporting the following Java Technologies: Java Specification Request (JSR) 139 Connected, Limited Device Configuration (CLDC) 1.1 and Mobile Information Device Profile (MIDP) 2.0, JSR 118 or higher.

Packages and Detection

The NokiaMaps API for Java ME is modular and contains separate packages for maps, places, touch components, directions (routing) and KML data rendering. If an application does not require certain packages, you can reduce its size by excluding them.

The entry point to the API is the maps-core.jar library (see also Quick startQuick Start). It contains all the code necessary to display a pannable and zoomable map, as well any common code for the API. Further JARs may be required on the classpath to access additional functions, and they must then be exported as part of the final package.

**Table:** Selectable libraries NokiaMaps API for Java ME
Library JAR Name	Description
`maps-core.jar`	This JAR is required for all map-based applications.
`maps-components.jar`	This JAR offers a series of custom `MapComponents` (such as Infobubbles) and creates a framework for touchable `MapComponents`, such as buttons.
`maps-components.jar`	This JAR extends the `maps-components.jar` to add gesture support to the `MapComponents`. The device must support the Gesture APIGesture API 1.2 or higher.
`maps-kml.jar`	This JAR (along with an implementation of JSR-172) is required to process and display KML data.
`places.jar`	This JAR is required to access the places, geocoding, reverse geocoding and the sharing functions.
`routing.jar`	This JAR is required to access the routing service.

The Maps API for Java ME is usually included as an optional plug-in when installing an associated Software Development Kit (SDK) for Java ME . All the library JARs can be found in the ./plugins/maps_api/lib directory of the installed SDK. The associated JavaDoc can be found in the./plugins/maps api/doc directory of the installed version of the SDK.

Licensing

The Nokia Maps API for Java ME is free to use under the Nokia Maps API terms and conditionsNokia Maps API terms and conditions and subject to limitations set out on the pricing plans page: http://developer.here.net/web/guest/plans http://developer.here.net/web/guest/plans. This site also outlines alternative licensing options for developers.

Note: The use of any of the Nokia Location Platform APIs must be accompanied by authentication credentials. For information on how to obtain and use the credentials, please see

Acquiring Credentials.

Using Maps API

To use Maps API to display map, see: Displaying maps on screen, and check out the Tourist Attractions code example.
To use Maps API and Location API to display the device's current location and a target location, and calculate a route between the two, download the source code (MapExample.zip).
For other uses of Maps API, see: Code examples at Nokia Developer Projects.

For more information, see Maps API for Java ME .