HERE Maps API - Converting from JavaScript to KML
15 Jan
2012
KML has emerged as the de facto standard for online mapping data. This article explains how to convert an existing JavaScript-based Map into a KML-based solution and details the likely benefits to be gained by implementing such a solution
Contents |
Introduction : What is KML
Keyhole Markup Language (KML) is an XML notation for geographic applications. It allows both two-dimensional maps and three-dimensional maps to display additional information overlaying the basic map. The current version of the HERE Maps API for JavaScript is KML compliant and is able to parse KML files. By separating the geographical application data (the model) from the method of rendering that data on the map (the view), the same KML data may be used be multiple applications. For example, most major search engines, such as Google, Bing and Ask are able to read KML files directly and return the map in their search results. Also since KML is a de facto standard, mapping libraries are optimised to use it, therefore converting from a Home-brew JavaScript solution to a KML solution should result in a faster rendering performance for basic map data.
What aspects of KML are relevant for two-dimensional maps?
KML was originally developed for three-dimensional Earth viewers, therefore only a subset of KML is strictly relevant to two-dimensional maps. Fortunately this also covers a high percentage of 2d-mapping use cases.
KML is able to:
- Specify icons and labels to identify locations.
- Specify additional information (e.g. address, phone number) to associate with a specific location.
- Define other elements such as polygons and polylines and attach them to the map.
- Define styles to specify feature appearance.
- Write HTML descriptions of features, including hyperlinks and embedded images
- Use folders for hierarchical grouping of features
Comparison between Nokia Map elements and the KML syntax
Map Marker
A MapMarker is a KML <Placemark> with a <Point> geometry and an <IconStyle>
| Nokia Map | KML Syntax |
|---|---|
marker = new nokia.maps.map.Marker( |
<Placemark> |
As can be seen, there is a one-to-one correspondence between the Marker attributes and the KML <Point> attributes. The coordinates of the marker are specified in the <coordinates> tag, although longitude and latitude are reversed, and altitude is added. Since altitude is irrelevant for a two-dimensional map, a placeholder of zero can be used. The icon of the marker is defined by the <href> tag. The anchor of the marker is specified in the <hotSpot> tag, with the Point offsets held in the x and y attributes. Note that <hotSpot> can be defined in three different ways, correspond directly,the xunit atttibute and the yunit attribute must be set to "pixels"
Map Standard Marker
A Map StandardMarker can be defined as KML <Placemark> with a <Point> geometry and a <styleUrl>
| Nokia Map | KML Syntax |
|---|---|
<script type="text/javascript" |
<Style id='FF0000'> |
KML does not have the concept of a StandardMarker. If a <Point> is defined without styling, it is up to the rendering library to decide what icon to use on the marker. Obviously if HERE Maps is used, the <Point> will default to the Nokia StandardMarker. Nokia's StandardMarker has a brush attribute which changes the color of the marker. This cannot be replicated directly in KML. However, it is possible to approximate this using a KML <Style>.
Firstly we need to create custom icons for the various default RGB colors:
| Icon | Color | Style Id | URL | ||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
 |
Black | 000000 | images/0/02/000000.png|- |  |
Blue | 0000FF | images/e/e5/0000FF.png|- |  |
Red | FF0000 | http://www.developer.nokia.com/Community/Wiki/images/9/99/FF0000.png | ||||||||||||||||||||||||||||||||||||||||||
 |
Yellow | FFFF00 | images/6/68/FFFF00.png|- |  |
White | 000000 | images/d/de/FFFFFF.png|}
Thereafter, we can use the <styleURL> element of the <PlaceMark> to render the <Point> using the icon defined in the <Style> Marker.  Note: The RGB value of the color is the same as the id of the <Style> containing the image of a marker with that color. This is how the <Style> and <styleUrl> can link together. InfoBubbleAn Infobubble can be defined as KML <Placemark> with a <description> tag
The <description> tag is defined as being "User-supplied content that appears in the description balloon". As such it is analogous to the Nokia Map Infobubble. The usual way to create an InfoBubble is to associate additional data with the marker (in this case by adding an .html attribute) and then displaying the info bubble by adding an onclick event. Note: The naming of the additional data element is arbitrary, but frequently something like .html or .description will be used. Many KML feeds make the assumption that the consumer of the KML file will render HTML, and therefore place HTML tags directly in the description - this could be avoided by using KML placeholders and creating a <BalloonStyle>, but this is beyond the scope of this article. PolylineA Polyline can be defined as KML <Placemark> with a <LineString> geometry and a <LineStyle>
Again there is a one-to-one correspondence between the Polyline attributes and the KML <LineString> attributes. The coordinates of the route are specified in the <coordinates> tag, although longitude and latitude are reversed, and altitude is added - this can be left as a placeholder of zero if desired. The lineWidth of the route is defined by the <width> tag. Similarly the the strokeColor of the route corresponds to the <color> tag. There is however a difference in the encoding here, as HERE Maps uses RGB encoding, and the KML standard uses ABGR encoding, so the first two bytes define the opacity (which can be defaulted to FF) and the red and blue ordering is reversed. The saveMapObjects function - a JavaScript library to convert the Map to KMLNokia Map data is stored in map.objects - it is a relatively simple matter to traverse the markers and obtain the necessary data to create KML <Point>s. Note that since the additional data element for the pop-up description is arbitrary, the .html attribute in this example may need to be altered to cope with other maps. var markerData = new Object();
var lineData = new Object();
The collected data may then be written out as KML <Placemark>s using the method below: var kmlOutput = "<?xml version='1.0' encoding='UTF-8'?><kml xmlns='http://www.opengis.net/kml/2.2'><Document>\n";
Working Example : Premiership Teams Warning: in order to load a KML file successfully, the KML file should be hosted on the same domain as the JavaScript or the results may be unpredictable. Some browsers will automatically prohibit cross-domain access.
For the working example the final line of the JavaScript will need to be altered to: kml.parseKML("http://example.com/premiership.kml");  Tip: The KML reader of the HERE Maps API for JavaScript will ignore elements it is unable to interpret. KML readers vary and are more or less forgiving in the strictness of interpreting the KML specifications. It is recommended that you validate your KML syntax yourself through an online validator such as: http://feedvalidator.org
The attached coded example - Media:Premiership.zip - contains three versions of the same map:
Each file also contains standard timing code, to display the length of time taken to load the map. Obviously the rate at which map data is generated on screen will depend upon a variety of factors such as the performance of the browser and the load of the Internet at the time of test. For the attached coded example, the following metric was generated for three runs of the maps using the same browser. In all cases, the cache was not cleared for each run. Firefox
The obvious conclusion to be drawn, is that using a KML file should increase the performance of the rendering of the map. Additional BenefitsSince KML is a de facto standard, the same data file can be used by multiple applications. Most major search engines, such as Google, Bing and Ask are able to crawl KML files if the website contains an appropriate sitemap.xml file. For full details of the protocol, please read the definitions on: http://www.sitemaps.org/ Example Sitemap.xml File <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" Additionally since KML is merely a subset of XML, Java ME mobile phone applications can read the same data using JSR-172. The screen shot below shows the same KML file embedded in a KML Reader running in the Java ME emulator:
SummaryConverting to KML format is relatively simple, and the process can be automated. The benefits of using KML format include faster rendering and the separation of mapping data from the code. Use of a standard format promotes cross-application use of the same data, and allows faster development of mapping applications across multiple platforms.
|
sourcecode= [[Media:Premiership.zip | installfile= | devices= Internet Explorer, Google Chrome, Firefox, Opera | sdk= | platform= Web | devicecompatability= | dependencies= HERE Maps 2.2.3 | signing= | capabilities= | keywords= HERE Maps, JavaScript, KML | language= | translated-by= | translated-from-title= | translated-from-id= | review-by= | review-timestamp= | update-by= | update-timestamp= | creationdate= 20120105 | author= jasfox
}} |
(no comments yet)