Using KML documents with BlackBerry Maps

Development Guide

Search This Document

Download PDF

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

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

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

Import the required classes.
```
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);
```

Code sample: Invoking BlackBerry Maps by using a KML document

import net.rim.blackberry.api.invoke.*;
  
public class invokeMaps
{
    public invokeMaps()
    { 
        MapsArguments ma = new MapsArguments
          (MapsArguments.ARG_KML, "http://www.example.com/document.kml");
        Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, ma);
    }
}

Next topic: Opening BlackBerry Maps from the BlackBerry Browser

Previous topic: Open BlackBerry Maps by using a local search

Was this information helpful? Send us your comments.

Global Navigation

Development Guide

Local Navigation