/ DEVELOPER DAY

LOCATION AND MAPS API

Cao PhongDeveloper Tech Support ManagerAug 07, 2013

/ DEVELOPER DAY

POSITIONING METHODS• Generally also positioning methods can be divided in two main groups: Network

based positioning, and GPS based positioning.

500 m 2000 m 4000 m

Urban: 50% within 250 m80% within 500 m

100 % hit rate

100 m

Sub – Urban: 50% within 600 m80% within 1.5 km

80-90 % hit rate

Rural: 50% within 1500 m

80% within 3 km60-90 % hit rate

WLAN: Up to 30m precision in

urban areas

Cell-id precision offered across Asha range of phonesCell-id precision offered across Asha range of phones Only on WLAN phonesOnly on WLAN phones

/ DEVELOPER DAY

JSR-179 : JAVAX.MICROEDITION.LOCATION

Interface SummaryLocationListener 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 SummaryAddressInfo 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.

Class SummaryLocationUtil A utility class that provides a static method for retrieving a LocationProvider matching the defined location methods.

com.nokia.mid.location

/ DEVELOPER DAY

LOCATION API USAGE EXAMPLE//Online cell ID and/or WLANint[] methods = {(Location.MTA_ASSISTED | Location.MTE_CELLID | Location.MTE_SHORTRANGE | Location.MTY_NETWORKBASED)};

//Assisted GPSint[] methods = {(Location.MTA_ASSISTED | Location.MTE_SATELLTITE | Location.MTY_TERMINALBASED)};

//Standalone GPSint[] methods = {(Location.MTA_UNASSISTED | Location.MTE_SATELLTITE | Location.MTY_TERMINALBASED)};

//Offline cell IDint[] methods = {(Location.MTA_UNASSISTED | Location.MTE_CELLID | Location.MTY_TERMINALBASED)};...LocationProvider providerLocation location;QualifiedCoordinates coordinates;...provider = LocationUtil.getLocationProvider(methods, null);location=provider.getLocation(50000);coordinates=location.getQualifiedCoordinates();

/ DEVELOPER DAY

WORKING WITH

MAPS PROJECTS

/ DEVELOPER DAY

MAIN FEATURESFeature DescriptionMaps 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 Suppport 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.

/ DEVELOPER DAY

MAPS API REQUIREMENTS

7

• You need to have Application ID and token, and to get them got to: https://developer.here.com/myapps• Register to the site,• Add new application to obtain the ID & Token

• Add the token to the java codes

ApplicationContext ctx = ApplicationContext.getInstance();ctx.setAppID(”Your_App_Id_Here");ctx.setToken(”Your_Token_Here");

/ DEVELOPER DAY

MAP API BASIC FUNCTIONALITY

/ DEVELOPER DAY

ARCHITECTURAL DESIGN MapCanvas - a concrete instantiation of the

javax.microedition.lcdui.Canvas class. Handles the low-level graphics painting the map and the delivery of events .

MapDisplay – defines the part of the World to be displayed, and encapsulates the details of any custom points of interest. That is it contains MapObjects

MapObjects may be also be placed within a MapContainer

Use the MapFactory to create MapObjects and add them to the MapDisplay.

Both the MapDisplay and MapContainers are themselves MapObjects

/ DEVELOPER DAY

THE MINIMAL IMPLEMENTATION (1/2)

1. Set credentials in the ApplicationContext

2. Create a MapCanvas

3. Set it as the current Display

ApplicationContext.getInstance().setAppID("YzY4v .... McwY");ApplicationContext.getInstance().setToken("WuTGn .... uM2Q");

MapCanvas mapCanvas = new MapCanvas(display) {public void onMapUpdateError(String string, Throwable thrwbl, boolean bln) {}public void onMapContentComplete() {}

};

Display display = Display.getDisplay(this);display.setCurrent(mapCanvas);

/ DEVELOPER DAY

THE MINIMAL IMPLEMENTATION (2/2)import javax.microedition.midlet.MIDlet;import javax.microedition.lcdui.*;import com.nokia.maps.map.MapCanvas;import com.nokia.maps.common.*;

public class Hello extends MIDlet implements CommandListener{private final Command exitCommand;

public Hello(){exitCommand = new Command("Exit", Command.EXIT, 1);

}public void startApp() {ApplicationContext.getInstance().setAppID("YzY4 ... 0McwY");ApplicationContext.getInstance().setToken("WuTGn ... sspuM2Q");Display display = Display.getDisplay(this);

MapCanvas mapCanvas = new MapCanvas(display) {public void onMapUpdateError(String string, Throwable thrwbl, boolean bln) {}public void onMapContentComplete() {}

};display.setCurrent(mapCanvas);

mapCanvas.setTitle("Hello Map");mapCanvas.addCommand(exitCommand);mapCanvas.setCommandListener(this);

}public void commandAction(Command command, Displayable displayable){

if (command == exitCommand){notifyDestroyed();

}}public void pauseApp() {}public void destroyApp(boolean unconditional) {}

}

/ DEVELOPER DAY

SETTING MAP TYPE• The Nokia Maps API for Java ME allows you to choose the map

type you want to display. • The MapSchemeType interface defines a series constants that

represent the available base map types.

Map type Constant Description

NORMAL This is the default base type showing a conventional map optimized for mobile displays.

SATELLITE This is a type that offers a view of the map based on satellite imagery

HYBRID This is a type that offers a satellite view of the map including labels optimized for mobile displays.

TERRAIN This is a type that shows a map based elevation profile imagery and is optimized for mobile displays.

TRANSIT This is a type of map that emphasizes public transport links and is optimized for mobile displays.

// Activate satellite imagery on the Map Display: mapCanvas.getMapDisplay().setBaseMapType(MapSchemeType.SATELLITE);

/ DEVELOPER DAY

MAP TYPES – ADVANCED METHODAdditional map types, beyond the five standard MapSchemeTypes are also available online. A list of available MapProviders may be requested from the Nokia Map tile service provider.

1) Implement a MapSchemeListener and call getAvailableMaps()public class MapTypes ...implements MapSchemeListener...{public void startApp() {

mapCanvas.getMapDisplay().getAvailableBaseMaps(this);}}

2) Handle Success and Failurepublic void onMapSchemesAvailable(MapProvider[] mapSchemes){...}public void onMapSchemesError(java.lang.Throwable reason){...}

3) Set the BaseMapType from MapProviders received

mapCanvas.getMapDisplay().setBaseMapType(myMapSchemes[sellected]);

/ DEVELOPER DAY

MAP TYPES, EXAMPLES:

/ DEVELOPER DAY

MAP LANGUAGES

ARA Arabic Worldwide

CHI Chinese (Simplified) Worldwide

CHT Chinese (Traditional) WorldwideDUT Dutch non-China seENG English WorldwideRE French WorldwideGER German WorldwideGRE Greek non-China seHEB Hebrew non-China se

ND Bahasa Indonesia non-China seTA Italian WorldwidePER Persian non-China sePOL Polish Worldwide

POR Portuguese non-China seRUS Russian WorldwideSPA Spanish Worldwide

• By default Map language is English• To change the language Just set the

DefaultLanguage in the ApplicationContext

ApplicationContext.getInstance().setAppID("YzY4vS ...cwY");ApplicationContext.getInstance().setToken("WuT ...uM2Q");ApplicationContext.getInstance().setDefaultLanguage("RUS");

/ DEVELOPER DAY

MAP LANGUAGES, EXAMPLES

/ DEVELOPER DAY

CHANGING THE MAP VISIBLE AREA• Basic Maps related functionalities with Java ME Maps API are implemented in

the com.nokia.maps.map.MapDisplay class

• You can get the current location with getCenter function, and change the location with setCenter fucntion.

• The visible area is controlled with zoomlevel, and to obtain current zoom value you can use getZoomLevel function, and similarly the setZoomLevel can be used to set new zoom value.

• Also getBoundingBox function can be used to determine the bounding box covered by the current display’s visible area

• And there is also zoomTo function, which takes bounding box as an argument, and thus it can be used to set visible geo areas to the display.

/ DEVELOPER DAY

MAP OBJECTS

/ DEVELOPER DAY

MAP MARKERS (1/2)

MapStandardMarker:allows adding various Geometric Shapes with text, and custom colors (with opacity as well)

MapMarker: Used to add graphical icons.

Default marker is a ‘Nokia Blue’ Balloon

Markers highlight Points of interest at a specified location on the map. Markers are created with MapFactory class, and there are two classes for markers which you can use:

/ DEVELOPER DAY

MAP MARKERS (2/2)

MapFactoryMf = mapCanvas.getMapFactory();

MapContainer MapMarker = Mf.createMapContainer();

MapStandardMarker m1 = Mf.createStandardMarker(new GeoCoordinate(52.45705,13.21173, 0 ), 40, "1", MapStandardMarker.PENTAGON);

MapMarker.addMapObject(m1);

MapStandardMarker m2 = Mf.createStandardMarker(new GeoCoordinate(52.45705,13.21173, 0 ), 40, "1", MapStandardMarker.BALLOON);

m2.setColor(0xaaff8c00);MapMarker.addMapObject(m2);

mapCanvas.getMapDisplay().addMapObject( MapMarker );

Image markerIcon = Image.createImage("/Pois.png");MapMarker oneMarker = Mf.createMapMarker(new GeoCoordinate(52.7, 13.4, 0 ), markerIcon);

mapCanvas.getMapDisplay().addMapObject(oneMarker);

You can add the markers separately into Map, or you can also use the MapContainerto arrange the markers in groups, and then add the MapContainerto the map.

/ DEVELOPER DAY

POLYLINES• Polylines are created using the MapFactory.

• A MapPolyline is a series of connected points

• Note that MapPolyline implements function returning GeoBoundingBox,which can be used for fitting it to the display.

MapPolyline polyline = null;

GeoCoordinate[] polylinCoord = new GeoCoordinate[4];polylinCoord[0] = new GeoCoordinate(60.27, 24.81, 0);polylinCoord[1] = new GeoCoordinate(60.35, 24.70, 0);polylinCoord[2] = new GeoCoordinate(60.19, 24.57, 0);polylinCoord[3] = new GeoCoordinate(60.27, 24.81, 0);

polyline = mapCanvas.getMapFactory().createMapPolyline(polylinCoord);polyline.setColor(0xFF43A5FF);

mapCanvas.getMapDisplay().addMapObject(polyline);mapCanvas.getMapDisplay().zoomTo(polyline.getBoundingBox(),false);

/ DEVELOPER DAY

POLYGONS Polyons are also created using the MapFactory.

A MapPolygon is the area within a closed loop of points

Note that also MapPolygon implements function returning GeoBoundingBox, which can be used for fitting it to the display.

MapPolygon polygon = null;

GeoCoordinate[] polylinCoord = new GeoCoordinate[4];polylinCoord[0] = new GeoCoordinate(60.27, 24.81, 0);polylinCoord[1] = new GeoCoordinate(60.35, 24.70, 0);polylinCoord[2] = new GeoCoordinate(60.19, 24.57, 0);polylinCoord[3] = new GeoCoordinate(60.27, 24.81, 0);

polygon = mapCanvas.getMapFactory().createMapPolygon(polylinCoord);polygon.setColor(0xAA43A51B);

mapCanvas.getMapDisplay().addMapObject(polygon);mapCanvas.getMapDisplay().zoomTo(polygon.getBoundingBox(),false);

/ DEVELOPER DAY

ADDITIONAL OBJECTS

There are also convenience classes for Rectangle and Circle available

GeoBoundingBox rectnaglebox = new GeoBoundingBox(new GeoCoordinate(60.35, 24.60,0), new GeoCoordinate(60.25, 24.80,0));MapRectangle rectnagle = mapCanvas.getMapFactory().createMapRectangle(rectanglebox);mapCanvas.getMapDisplay().addMapObject( rectnagle );

MapCircle myCircle = mapCanvas.getMapFactory().createMapCircle(5000.0,newGeoCoordinate(60.30, 24.70,0)); mapCanvas.getMapDisplay().addMapObject( myCircle );

/ DEVELOPER DAY

MAP APISERVICES

/ DEVELOPER DAY

MAP API SERVICES: CONTENT

Search (Geocoding and Reverse Geocoding) Places Search Routing Sharing

/ DEVELOPER DAY

MAPS API GENERAL REQUIREMENTS

26

Do remember to add libraries as required by the API parts used

Library JAR Name Descriptionmaps-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-gesture.jar This JAR extends the maps-components.jar to add gesture support to the MapComponents. The device must support the Gesture 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.

/ DEVELOPER DAY

GEOCODING SEARCH

• Geocoding Finds a location on the Map from a given Address• Reverse Geocoding Finds the Address for a given geographic

location• Search Finds Places of interest for given search criterias• All service requests can be used either synchronous or

asynchronous way.• Asynchronous search is preferred

/ DEVELOPER DAY

public void onRequestComplete(GeocodeRequest arg0, com.nokia.places.Location[] result){}

public void onRequestError(GeocodeRequest request, java.lang.Throwable error) {}

GEOCODING1. Implement a GeoCodeRequestListener

2. Create a GeoCodeRequest

3. Handle Success or Failure

public class GeoCoding ... implements ... GeocodeRequestListener

PlaceFactory sf = PlaceFactory.getInstance();GeocodeRequest gRs = sf.createGeocodeRequest(); gRs.geocode(geostr, null, this);

/ DEVELOPER DAY

REVERSE GEOCODING

1. Implement a ReverseGeocodeRequestListener

2. Create a ReverseGeocodeRequest

3. Handle Success or Failure

public class ReverceGeoCoding … implements ReverseGeocodeRequestListener

PlaceFactory sf = PlaceFactory.getInstance();ReverseGeocodeRequest revG = sf.createReverseGeocodeRequest();revG.reverseGeocode(mapCanvas.getMapDisplay().getCenter(),this);

public void onRequestComplete(ReverseGeocodeRequest request, com.nokia.places.Location[] result){}

public void onRequestError(ReverseGeocodeRequest request, java.lang.Throwable error){}

/ DEVELOPER DAY

PLACES SEARCH1. Implement a ResultPageRequestListener

2. Create a ResultPageRequest

3. Handle Success or Failure

4. More details can be obtained by interrogating the ResultPage

public class MapSearch … implements ResultPageRequestListener

PlaceFactory sf = PlaceFactory.getInstance();ResultPageRequest Pls = sf.createResultPageRequest(); GeoBoundingBox bboxx = new GeoBoundingBox(topLeft,btRight);Pls.search(geostr, bboxx,this);

public void onRequestComplete(ResultPageRequest arg0, ResultPage result) {}public void onRequestError(ResultPageRequest arg0, Throwable error) {}

com.nokia.places.Place FirstPlace = result.getItems()[0].getId();FirstPlace.getCategories();FirstPlace.getLocation();FirstPlace.getName();FirstPlace.getContacts();...

/ DEVELOPER DAY

RESULTPAGEREQUEST OPTION• Flexible Local Search

• A free text search using the search() method

• category search ranked by popularity using the explore() method

• A category search ranked by distance using the around() method

• A specified location query using the here() method

• Within the API, large collections are paginated using hyperlinks to point to the next page of items. Further requests may be made to obtain a subsequent page of items.

if (result.hasNextPage()){result.nextPage(this);

}

/ DEVELOPER DAY

ROUTING1. Implement a RouteListener

2. Create a RouteRequest

3. Handle Success or Failure

public class SimpleRouting …implements RouteListener

RouteFactory rm = RouteFactory.getInstance();

WaypointParameterList wpl = new WaypointParameterList();wpl.addCoordinate(startMarker.getCoordinate());wpl.addCoordinate(enddMarker.getCoordinate());

Mode modde = new Mode();modde.setRoutingOptions(new String[] {RouteFeature.MOTORWAY});modde.setFeatureWeights( new int[] {RouteFeatureWeight.AVOID});

modde.setRoutingType(RoutingType.FASTEST);modde.setTrafficMode(TrafficMode.DEFAULT); modde.setTransportModes(new int[] { TransportMode.CAR});

RouteRequest rRs= rm.createRouteRequest();rRs.calculateRoute(wpl,modde, this);

public void onRequestComplete(RouteRequest request, Route[] routes){}public void onRequestError(RouteRequest request, java.lang.Throwable error){}

/ DEVELOPER DAY

ROUTING MODE

• routingType - type of the routing • ECONOMIC , FASTEST , SHORTEST

• transportModes - transport mode array

• CAR, PEDESTRIAN, PUBLICTRANSPORT

• featureWeights - feature weights array• AVOID, NORMAL, PREFER, SOFTEXCLUDE,

STRICT_EXCLUDE

• routingOptions - routing options array • HOVLANE

• MOTORWAY

• PARK

• PUBLICTRANSPORT

• RAILFERRY

• STAIRS

• TOLLROAD

• TUNNEL

/ DEVELOPER DAY

SHARING• Creates short encrypted URLs for the RESTful Maps API

• Send URL as an SMS for a client to receive a static map.

• Service forwards to maps.nokia.com or m.maps.nokia.com on capable browsers

http://m.nok.it/HGkAAAAazMzMFldk

SharingManager shareM = SharingManager.getInstance();String Url = shareM.getMapUrl(mapCanvas.getMapDisplay());

/ DEVELOPER DAY

SHARING- OPTIONS

• getPlaceUrl: returns a sharable URL that refers to a place. • getPoiUrl: returns a sharable URL that refers to an image that

contains a map with the map centered on a group of POIs.• getLocationUrl: returns a sharable URL that refers to an image that

contains a map with the map centered on the location.

/ DEVELOPER DAY

SPECIAL THANKS

Jason Fox

/ DEVELOPER DAY

THANK YOUQUESTIONS?