HERE Maps API - How to display KML file data on the map
Contents |
Introduction
HERE Maps API version 2.2.4 offers support for KML data formatted files and displaying the containing data on the HERE Maps. This article will offer an overview to KML, structure and how it can be used within HERE Maps.
Summary
HERE Maps API supported web browser (basically any modern web browser)
Important note about maps credentials
Nokia provides several services options within the Maps API offering. The service is free to use, but you must obtain and use authentication and authorization credentials to use the services. Please read the Terms and Conditions and check the Pricing Plans page to decide which business model best fits your needs. Authentication requires unique Maps API credentials, namely an AppId and a token. You can get these credentials free for free following the instructions here
Implementation
HERE Maps API has built in support for KML. It is an abbreviation for Keyhole Markup Language, representing an XML notation for expressing geographic annotation and visualization within Internet-based, two-dimensional maps and three-dimensional Earth browsers. KML was developed as a Google Maps feature by company called Keyhole, Inc, later acquired by Google.
Today, KML is an international standard of the Open Geospatial Consortium (http://en.wikipedia.org/wiki/Open_Geospatial_Consortium) and is supported in the HERE Maps API.
Restrictions in HERE Maps
HERE Maps API does not currently support 3D so, these values if provided would be discarded by the API.- HERE Maps API does not currently support reading packaged KMZ files.
Structure
KML is structured as tag-based, with nested-elements and attributes and based on the XML standard. The tags are case-sensitive and they must appear exactly as they are listed in the official KML Reference, found within the OGC pages. The KML Reference indicates which tags are optional. Within a given element, tags must appear in the order shown in the Reference. The KML file can contain information for Markers, Places, images, Polygons, 3D models, textual descriptions, and so on. Common for all items placed is that they always have a longitude and a latitude. Additional data e.g. tilt, heading and altitude can be provided as "camera view". The KML file specifies a set of features (placemarks, images, polygons, 3D models, textual descriptions, etc.)
Example KML document
For the working example my_domain.com in the final line of the JavaScript will need to be altered as necessary.
kml.parseKML("http://my_domain.com/" + "kml_data_file.kml")
In this example we will have a simple KML document containing data for one Placemark, for Berlin, Alexanderplatz.
Please note that by the KML specification the coordinate is given in format: longitude, latitude.
File: kml_data_file.kml
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<Placemark>
<name>Berlin</name>
<description>Alexanderplatz, Berlin, Germany</description>
<Point>
<coordinates>13.41156,52.526666</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Example code
This code only works if a valid appID and token are supplied and the KML file to be parsed must be hosted on the same domain. Remember to add in your own AppId and Token and replace http://my_domain.com/ at the end of the code the location of the HTML and KML files.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Loading a KML file.</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<script type="text/javascript"
src="http://api.maps.nokia.com/2.2.4/jsl.js?with=all" charset="utf-8">
</script>
</head>
<body>
<div id="map" style="z-index: -1; left:0px; top:0px; width: 100%; height: 80%; position: absolute;"></div>
<script type="text/javascript">
/*<![CDATA[*/
/////////////////////////////////////////////////////////////////////////////////////
// Don't forget to set your API credentials
//
// Replace with your appId and token which you can obtain when you
// register on http://api.developer.nokia.com/
//
nokia.Settings.set( "appId", "YOUR APP ID GOES HERE");
nokia.Settings.set( "authenticationToken", "YOUR AUTHENTICATION TOKEN GOES HERE");
//
/////////////////////////////////////////////////////////////////////////////////////
var map = new nokia.maps.map.Display(document.getElementById("map"),
{ components: [ new nokia.maps.map.component.Behavior(),
new nokia.maps.map.component.ZoomBar(),
new nokia.maps.map.component.Overview(),
new nokia.maps.map.component.TypeSelector(),
new nokia.maps.map.component.ScaleBar(),
new nokia.maps.map.component.InfoBubbles()],
'zoomLevel': 4,
'center':[53.1, 13.1]});
var kml = new nokia.maps.kml.Manager();
// We define a callback function for parsing kml file,
// and then push the parsing result to map display
var onParsed = function (kmlManager) {
var resultSet;
// KML file was successfully loaded
if (kmlManager.state == "finished") {
// KML file was successfully parsed
resultSet = new nokia.maps.kml.component.KMLResultSet(kmlManager.kmlDocument, map);
resultSet.addObserver("state", function (resultSet) {
if (resultSet.state == "finished") {
// Retrieve map objects container from KML resultSet
container = resultSet.container;
// Add the container to the map's object collection so they will be rendered onto the map.
map.objects.add(container);
// Switch the viewport of the map do show all KML map objects within the container
map.zoomTo(container.getBoundingBox());
}
});
resultSet.create();
}
};
// Add an observer to kml manager
kml.addObserver("state", onParsed);
/////////////////////////////////////////////////////////////////////////////////////
// Start parsing a kml file with given url
// Note: please adapt the following path to the file you want to parse.
kml.parseKML("http://my_domain.com/" + "kml_data_file.kml");
/////////////////////////////////////////////////////////////////////////////////////
/*]]>*/
</script>
</body>
</html>
See this example online here
Geodetic reference systems in KML
For its reference system, KML uses 3D geographic coordinates: longitude, latitude and altitude, in that order. The longitude, latitude components are defined by the World Geodetic System of 1984 (WGS84). The vertical component (altitude) is measured from the WGS84 EGM96 Geoid vertical datum. If altitude is omitted from a coordinate string, e.g. (-122.917, 49.2623) then the default value of 0 (approximately sea level) is assumed for the altitude component, i.e. (-122.917, 49.2623, 0) is assumed. A formal definition of the coordinate reference system (encoded as GML) used by KML is contained in the OGC KML 2.2 Specification. This definition references well-known EPSG CRS components.
OGC standard process
The KML 2.2 specification was submitted to the Open Geospatial Consortium to assure its status as an open standard for all geobrowsers. In November 2007 a new KML 2.2 Standards Working Group was established within OGC to formalize KML 2.2 as an OGC standard. Comments were sought on the proposed standard until January 4, 2008,[4] and it became an official OGC standard on April 14, 2008.[5]
For more on the HERE Maps API
Please check out the HERE Maps API full documentation and API reference here:
You may also access the interactive API explorer
Tested with
Google Chrome: 20x Mozilla Firefox 12.0
Contents
Eman.Refaat - XMLHttpRequest cannot load Map.kml. Cross origin requests are only supported for HTTP.
Hi There, I try to load map.kml file on map but, I get this error : ( XMLHttpRequest cannot load Map.kml. Cross origin requests are only supported for HTTP.) I use the same code and same domain. any help
Thank youEman.Refaat 14:31, 31 January 2013 (EET)
Hamishwillee - Is the URL a local domain?
Hi Eman
As I understand it this happens when you do the request a local file rather than one hosted on a web server. Have you followed the instructions above and accessed via an http url?
If so and this still doesn't work I suggest you post on the Qt discussion board cross linking to here - that way you will get more eyes on the problem.
Regards
Hamishhamishwillee 00:02, 1 February 2013 (EET)
Eman.Refaat - Useing Local domain
First of All Thank you Hamish very much. I solve the problem through the following steps:
- open project on visual studio. - open (Web.config) file and add handler for kml file as :
<staticContent> <mimeMap fileExtension=".kml" mimeType="application/vnd.google-earth.kml+xml" /> </staticContent>the all file :
<configuration>
<system.web> <compilation debug="true" targetFramework="4.5"/> <httpRuntime targetFramework="4.5"/> </system.web> <system.webServer> <staticContent> <mimeMap fileExtension=".kml" mimeType="application/vnd.google-earth.kml+xml" /> </staticContent> </system.webServer></configuration>
Thank youEman.Refaat 13:54, 3 February 2013 (EET)
Hamishwillee - That's great
Thanks for adding your solution!
Regards
Hamishhamishwillee 01:05, 4 February 2013 (EET)
Rochedy - Kml reading error
Hi
i have some probems with reading kml files with your javascript api.
When i read this file
I have no problem, the feature is shown on the map.
but when i read this file :
The file is loaded but no feature is added on the map ! but my kml is good because on openlayers it work !
can you help me please ?
thank you !rochedy 11:10, 3 April 2013 (EEST)
Hamishwillee - Rochedy - author may no longer be monitoring this article
Hi Rochedy
This article was written in 2011 and the author may no longer be monitoring it.
You might want to raise this on the appropriate discussion board and cross link to this article in order to get more advice from more people.
Regards
Hamishhamishwillee 02:46, 4 April 2013 (EEST)