Maps

If you're using C++, the preferred way to invoke the BlackBerry Maps app from your app is to use the LocationMapInvoker and RouteMapInvoker APIs in your application. In addition to using the examples on this page to learn more about invoking the Maps app, see the Route Map Invoker sample application. However, you can also use the invocation attributes listed below to invoke the BlackBerry Maps app.

You can't use objective C for the attributes listed below.

Invoking the Maps app

Here are the attributes you can use to invoke the BlackBerry Maps app:

Attribute Value
Action bb.action.OPEN
MIME type application/vnd.rim.map.action-v1

The MIME type above defines all the actions that BlackBerry Maps handles. For example, setting the map center or starting navigation mode. The data passed in the invocation request is in JSON format.

Displaying a single location on the map

In addition to the action and MIME type attributes mentioned above, you can use the following data attributes to invoke the BlackBerry Maps app to display a single location on the map.

Attribute Values Description
center JSON object Defines the latitude, longitude, heading, and altitude of the map center. The default value depends on the location being displayed.
center.latitude [-90.0,90.0] Latitude in decimal degrees. This value is required.
center.longitude [-180.0,180.0] Longitude in decimal degrees. This value is required.
center.heading [0,359] Heading in degrees from true North
center.altitude An integer value greater than or equal to 0 Altitude in meters from ground. The default value is 0.
placemark JSON object Defines a location to add to the map as a pin and center the map on it
placemark.latitude [-90.0,90.0] Latitude in decimal degrees
placemark.longitude [-180.0,180.0] Longitude in decimal degrees
placemark.name String Location name
placemark.description String Location description
placemark.geocode true or false

Defines whether to geocode or reverse geocode the location. The default value is false.

If the value is true, geocode the placemark when a name is provided and latitude/longitude is not provided.

Also, if the value is true, reverse geocode the placemark when the name is not provided and latitude/longitude is provided.

geolocation true or false Find the current location of the device when the app launches. The default value is false.

Invoking the Maps app for navigation

You can use the following data attributes to invoke the BlackBerry Maps app in navigation mode.

Attribute Values Description
view_mode nav Invokes the Maps app and displays it in view_mode. By default, the view_mode opens the map screen but it can also open the navigation screen if provided with a nav value.
nav_start or nav_end JSON object Defines where navigation should begin or end. If the parameter is not provided, the navigation starts or ends at the current location.
nav_start.properties or nav_end.properties JSON object

Defines properties of the start or end location.

If the parameter is not provided, the nav_start.latitude, nav_end.latitude or nav_start.longitude, nav_end.longitude coordinates should be geocoded or reverse geocoded.

nav_start.properties.name or nav_end.properties.name String

The name of the start or end location. The default value is "". This attribute is required.

nav_start.properties.description or nav_end.properties.description String Description of the start or end location
nav_start.latitude or nav_end.latitude [-90.0,90.0]

Latitude of the start or end location

If the parameter is not provided, the BlackBerry Maps app attempts to geocode or reverse geocode using the values in nav_start.properties or nav_end.properties.

nav_start.longitude or nav_end.longitude [-180.0,180.0]

Longitude of the start or end location.

If the parameter is not provided, the BlackBerry Maps app attempts to geocode or reverse geocode using the values in nav_start.properties or nav_end.properties.

nav_options JSON object Defines the navigation options that can be used.
nav_options.nav_mode fastest or shortest Type of navigation to use: fastest for fastest route and shortest for shortest route. This attribute is required.
nav_options.avoid_highways true or false Defines whether to avoid highways or not.
nav_options.avoid_tolls true or false Defines whether to avoid tolls or not.

Showing the current location

The following code sample shows how to display the current location of the user in the center of the map, assuming the BlackBerry Maps application is open:

#include <bb/platform/LocationMapInvoker>
LocationMapInvoker lmi;

// Determine the current location of the user by setting 
// "geolocation" : true
// Set request properties then use go() to trigger the request 
// using the Invocation Framework.
lmi.setCurrentLocationEnabled(true);
lmi.go();

The geolocation value specifies whether the BlackBerry Maps application should determine the user's current location when the application starts. If geolocation is set to true, the user's current location is determined on the application start-up. This may take several seconds and initially the map may be centered on the last known position of the user. If geolocation is set to false the BlackBerry Maps application will use its default behavior and may or may not use geolocation to determine the user's current location when the application starts.

Directions from the current location

Because the start latitude, longitude, and address aren't specified, the default behavior is to use the device's current location. The following code sample shows how to get directions to a destination from the current location of the user:

#include <bb/platform/RouteMapInvoker>
RouteMapInvoker rmi;

// Latitude and Longitude values are expressed 
// in WGS 84 datum standard
rmi.setEndLatitude(43.653226);
rmi.setEndLongitude(-79.383184);
rmi.setEndName("My destination");
rmi.setEndDescription("Description of destination");
rmi.setEndAddress("Toronto, Ontario");
rmi.setNavigationMode(bb::platform::MapNavigationMode::FastestRoute);
rmi.setTransportationMode(bb::platform::MapTransportationMode::Car);
rmi.go();

Upon receiving the route request, the BlackBerry Maps application opens and transitions into the navigation mode.

Displaying a pin to mark a location

The following code sample shows how the display of an already opened BlackBerry Maps application can be re-centered and a pin dropped on the map to mark a location with a given latitude, longitude, and a name:

#include <bb/platform/LocationMapInvoker>
LocationMapInvoker lmi;

// Sample location set as Toronto
// Latitude and Longitude values are expressed 
// in WGS 84 datum standard
lmi.setLocationLatitude(43.652527);
lmi.setLocationLongitude(-79.381961);
lmi.setLocationName("Bubble Caption Name");
lmi.setLocationDescription("Details Screen Stuff");

//set "geocode" : false
lmi.setGeocodeLocationEnabled(false);

//set "geolocation" : false
lmi.setCurrentLocationEnabled(false);
lmi.go();

The geocode value refers to the location that is being requested. If geocode is set to true and a location name is provided in the request, the BlackBerry Maps application obtains the latitude and longitude values that correspond to the address specified in the LocationName. If geocode is set to true and a location name is not provided in the request, the BlackBerry Maps application reverse geocodes the provided location to find the address in the text format (for example, 295 Phillip Street, Waterloo, Ontario).

Displaying multiple points of interests

The following code sample shows you how to display multiple points of interest around the center of the map by using pins. The <Camera> coordinates specify the center of the map and <Altitude> is specified in meters.

#include <bb/platform/LocationMapInvoker>
LocationMapInvoker locationInvoker;

// kmlContent specifies all the necessary information about 
// a set of points of interest
locationInvoker.setKmlContent
("<kml xmlns=\"http://www.opengis.net/kml/2.2\">"
"<Folder>"

"<Camera><latitude>45.473459</latitude><longitude>-75.513089</longitude>
<altitude>4600</altitude></Camera>"

"<Placemark><name>Loc 1</name><description>Des 1</description>
<Point><coordinates>-75.514419,45.474362</coordinates></Point>
<address>addr1</address></Placemark>"

"<Placemark><name>Loc 2</name><description>Des 2</description>
<Point><coordinates>-75.522145,45.47388</coordinates></Point>
<address>addr2</address></Placemark>"

"<Placemark><name>Loc 3</name><description>Des 3</description>
<Point><coordinates>-75.534376,45.471954</coordinates></Point>
<address>addr3</address></Placemark>"

"<Placemark><name>Loc 4</name><description>Des 4</description>
<Point><coordinates>-75.544419,45.474362</coordinates></Point>
<address>addr4</address></Placemark>"

"</Folder>"
"</kml>");

locationInvoker.go();

For more information on how Cascades lets you integrate maps with the invocation framework, see Integrating with BlackBerry Maps.

You can also invoke the BlackBerry Maps by using the following invocation attributes:

Attribute Value
Action bb.action.OPEN
MIME type application/vnd.rim.map.action-v1

The MIME type above defines all the actions that BlackBerry Maps handles. For example, setting the map center or starting navigation mode. The data passed in the invocation request is in JSON format.

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus