Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Using KML documents with BlackBerry Maps

Keyhole Markup Language is an XML notation for expressing geographic annotation and visualization. You can use a KML document to store location information about places, buildings, point of interests, travel paths, bus routes, cycle paths, pictures, and so on. You can create a KML document, publish it on a web site, and view it using BlackBerry Maps.

For more information about the KML standard, see the complete specification for the OpenGIS KML Encoding Standard, or the associated KML Reference.

Supported KML elements

BlackBerry Maps supports the following KML elements:

KML element

Valid children

Supported in

kml

--

BlackBerry Java Development Environment4.6 or later

Document

--

BlackBerry JDE 5.0

address

--

BlackBerry JDE 5.0

description

--

BlackBerry JDE 5.0

name

--

BlackBerry JDE 5.0

phoneNumber

--

BlackBerry JDE 5.0

Style

Icon, IconStyle, LineStyle, PolyStyle, color, href, width

BlackBerry JDE 5.0

Placemark

coordinates, Point

BlackBerry JDE 4.6

Placemark

coordinates, innerBoundaryIs, LinearRing, LineString, outerBoundaryIs, Point, Polygon, styleUrl

BlackBerry JDE 5.0

Create a basic KML document

You can create a KML document in any text editor. The XML header and the KML namespace declaration are required and they must appear at the beginning of the document. You can mark a position on a map in BlackBerry Maps by using the <Placemark> element. The <Point> element specifies the longitude, latitude, and altitude of the location. Longitude ranges from -180 to +180, latitude ranges from -90 to +90. The altitude is optional and can be passed as 0. If you provide an altitude, the value must represent the altitude above sea level in meters.

Code sample: Creating a basic KML document

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
   <Placemark>
      <name>Ottawa</name>
      <description>Ottawa office</description>
      <Point>
         <coordinates>-90.86948943473118,48.25450093195546,0</coordinates>
      </Point>
   </Placemark>
</kml>

Displaying KML overlays on BlackBerry Maps

You can use a KML document to overlay an image at specific locations on a map in BlackBerry Maps.

In the KML document, the <Folder> element organizes the overlay information. You can use the <GroundOverlay> element to place an image, that is contained in the <Icon> element, over location on a map. The <LatLonBox> element specifies where to position the overlay on the map. You can repeat the <GroundOverlay> element block to specify new overlays and associated coordinates on the map.

Code sample: Displaying KML overlays on BlackBerry Maps

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
   <Folder>
      <name>Pictures</name>
      <visibility>0</visibility>
      <open>1</open>
      <GroundOverlay>
         <name>Glowing</name>
         <visibility>1</visibility>
         <description>Hot Spot</description>
         <Icon>
            <href>http://www.example.com/picture.png</href>
            <viewBoundScale>0.75</viewBoundScale>
         </Icon>
         <LatLonBox>
            <north>43.47685828285541</north>
            <south>43.47485739086753</south>
            <east>-80.53898253546113</east>
            <west>-80.54198566880086</west>
         </LatLonBox>
      </GroundOverlay>
   </Folder>
</kml>

Invoke BlackBerry Maps by using a KML document

Verify that you have created a KML document and published the document to a web site.

You can invoke BlackBerry Maps by passing in a MapsArguments object that specifies the URL of a KML document.

Code sample: Invoking BlackBerry Maps by using a KML document

import net.rim.blackberry.api.invoke.*;

//Create a class and a constructor to use to invoke BlackBerry Maps. 
public class invokeMaps
{
    public invokeMaps()
    {

//In the constructor, create an instance of the MapsArguments 
//class. Pass in the ARG_KML parameter and the URL of the KML document.
        MapsArguments ma = new MapsArguments
          (MapsArguments.ARG_KML, "http://www.example.com/document.kml");

//In the constructor, invoke Invoke.invokeApplication() to open 
//BlackBerry Maps. Pass in the MapsArguments object. 
        Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, ma);
    }
}

Opening BlackBerry Maps from the BlackBerry Browser

You can use the BlackBerry Browser to open BlackBerry Maps and load a location document. The web server MIME type must be correctly configured. Location documents have a MIME type of "text/vnd.rim.location.xloc".