Maps

You can invoke BlackBerry Maps by using the Invoke API with 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.

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.

Launching the Maps app

blackberry.invoke.invoke(
 {
    action: "bb.action.OPEN",
    type: "application/vnd.rim.map.action-v1"
 }
);

Launching the Maps app and getting the current device location

blackberry.invoke.invoke(
 {
    action: "bb.action.OPEN",
    type: "application/vnd.rim.map.action-v1",
    data: JSON.stringify(
        {
            "geolocation": true
        }
    )
 }
);

Launching the Maps app and centering the map at a particular location

blackberry.invoke.invoke(
 {
    action: "bb.action.OPEN",
    type: "application/vnd.rim.map.action-v1",
    data: JSON.stringify(
        {
            "center": {
                "latitude": 43.4667,
                "longitude": -80.5167,
                "altitude": 2000
            }
        }
    )
 }
);

Launching the Maps app and adding a pin to the map

blackberry.invoke.invoke(
 {
    action: "bb.action.OPEN",
    type: "application/vnd.rim.map.action-v1",
    data: JSON.stringify(
        {
            "placemark": {
                "latitude": 43.4667,
                "longitude": -80.5167,
                "name": "Waterloo",
                "description": "Waterloo, Ontario, Canada"
            }
        }
    )
 }
);

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.

Navigating from the current location to a given location

blackberry.invoke.invoke(
{
    action: "bb.action.OPEN",
    type: "application/vnd.rim.map.action-v1",
    data: JSON.stringify(
        {
            "view_mode": "nav",
            "nav_end":
            {
                "properties":
                {
                    "name": "Toronto",
                    "description": "City of Toronto",
                    "address": "Toronto, Ontario, Canada"
                },
                "latitude": 43.7,
                "longitude": -79.4
            }
        }
    )
}
);

Navigating from one location to another

blackberry.invoke.invoke(
{
    action: "bb.action.OPEN",
    type: "application/vnd.rim.map.action-v1",
    data: JSON.stringify(
        {
            "view_mode": "nav",
            "nav_start":
            {
                "properties":
                {
                    "name": "Work"
                },
                "latitude": 45.342533,
                "longitude": -75.930417
            },
            "nav_end":
            {
                "properties":
                {
                    "name": "Toronto",
                    "description": "City of Toronto",
                    "address": "Toronto, Ontario, Canada"
                },
                "latitude": 43.7,
                "longitude": -79.4
            },
            "nav_options":
            {
                "nav_mode": "shortest",
                "avoid_highways": true,
                "avoid_tolls": true
            }
        }
    )
}
);

Displaying uncompressed KML data on the map

To display uncompressed KML data on the map, you can use application/vnd.google-earth.kml+xml as the MIME type. Here's an example:

blackberry.invoke.invoke(
 {
    action: "bb.action.OPEN",
    type: "application/vnd.google-earth.kml+xml",
    data: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
    <kml xmlns=\"http://www.opengis.net/kml/2.2\"><Placemark>
    <name>Title</name>
    <description>Description</description><Point>
    <coordinates>-75.930417,45.342533,0</coordinates>
    </Point></Placemark></kml>"
 }
);

Last modified: 2014-12-04



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

comments powered by Disqus