×
Namespaces

Variants
Actions
(Difference between revisions)

HERE Maps API - How to display KML file data on the map

From Nokia Developer Wiki
Jump to: navigation, search
Maveric (Talk | contribs)
(Maveric -)
 
jasfox (Talk | contribs)
m (Jasfox - update to 2.2.4)
(23 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[[Category:Web]][[Category:Location]]
+
[[Category:Nokia Maps]][[Category:Code Snippet]][[Category:JavaScript]]
 +
{{ArticleMetaData
 +
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
 +
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 +
|devices= Internet Explorer, Firefox, Google Chrome, Opera
 +
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Nokia Qt SDK 1.1]) -->
 +
|platform= Web browser
 +
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 +
|dependencies=Nokia Maps 2.2.4
 +
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 +
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 +
|keywords= Nokia Maps, JavaScript, KML
 +
|id= <!-- Article Id (Knowledge base articles only) -->
 +
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 +
|translated-by= <!-- [[User:XXXX]] -->
 +
|translated-from-title= <!-- Title only -->
 +
|translated-from-id= <!-- Id of translated revision -->
 +
|review-by=<!-- After re-review: [[User:username]] -->
 +
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 +
|update-by=[[User:jasfox]]
 +
|update-timestamp=20120210
 +
|creationdate=20111027
 +
|author=[[User:Maveric]]
 +
}}
 +
{{SeeAlso|
 +
* [http://developer.here.net/javascript_api Nokia Maps API]
 +
*  [[Nokia Maps API - How to create a KML data file]]
 +
*  [[Nokia Maps API - Converting from JavaScript to KML]]
 +
*  [[Nokia Maps API - Converting any data file to KML]]
 +
* [[Nokia Maps API - Create map markers from XML data]]
 +
* [http://developer.here.net/apiexplorer/examples/api-for-js/data-visualization/map-with-interactive-kml-objects.html Loading a KML file example]
 +
}}
 
== Introduction ==
 
== Introduction ==
  
 
+
Nokia Maps API version 2.2.4 offers support for KML data formatted files and displaying the containing data on the Nokia Maps. This article will offer an overview to KML, structure and how it can be used within Nokia Maps.
The version 2.0 of Nokia Maps API offers support for KML data formatted files and displaying the containing data on the Nokia Maps. This article will offer an overview to KML, structure and how it can be used within Nokia Maps.
+
  
 
== Summary ==
 
== Summary ==
Line 9: Line 39:
 
Nokia Maps API supported web browser (basically any modern web browser)
 
Nokia Maps API supported web browser (basically any modern web browser)
  
==Important about Nokia Maps credentials==
+
==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
With Nokia Maps API you can start without having any credentials given, but you might face a performance gap. In order to get the full potential out of the offering, you must get the credentials that authenticate your application against the Services. Please read through the Location API.For more information on how to obtain the credentials, please start with the  Nokia Maps API Developers Guide section "Acquiring API credentials"
+
[http://developer.here.net/terms_conditions Terms and Conditions] and check the [http://developer.here.net/web/guest/plans 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 [http://developer.here.net/docs/maps_js/topics/credentials.html#acquiring-credentials here]
  
 
==Implementation==
 
==Implementation==
Line 18: Line 48:
 
Nokia 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.
 
Nokia 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.wikipeia.org/wiki/Open_Geospatial_Consortium) and is supported in the Nokia Maps API.
+
Today, KML is an international standard of the Open Geospatial Consortium (http://en.wikipedia.org/wiki/Open_Geospatial_Consortium) and is supported in the Nokia Maps API.
 
+
  
 
==Restrictions in Nokia Maps==  
 
==Restrictions in Nokia Maps==  
  
Nokia Maps API does not currently support 3D so, these values if prNokiaded would be discarded by the API.- Nokia Maps API does not currently support reading packaged KMZ files.
+
Nokia Maps API does not currently support 3D so, these values if provided would be discarded by the API.- Nokia Maps API does not currently support reading packaged KMZ files.
  
==Strucure==
+
==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 prNokiaded as "camera view".  The KML file specifies a set of features (placemarks, images, polygons, 3D models, textual descriptions, etc.)  
+
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==
 
==Example KML document==
 +
 +
{{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 ''my_domain.com'' in the final line of the JavaScript will need to be altered as necessary.
 +
<code javascript>
 +
kml.parseKML("http://my_domain.com/" + "kml_data_file.kml")
 +
</code>
 +
and both the HTML and the kml_data_file.kml should be placed on  ''http://my_domain.com/''
 +
 +
}}
  
 
In this example we will have a simple KML document containing data for one Placemark, for Berlin, Alexanderplatz.
 
In this example we will have a simple KML document containing data for one Placemark, for Berlin, Alexanderplatz.
Line 37: Line 75:
 
File: kml_data_file.kml
 
File: kml_data_file.kml
  
<code>
+
<code xml>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<kml xmlns="http://www.opengis.net/kml/2.2">
 
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
+
    <Document>
<Placemark>   
+
        <Placemark>   
<name>Berlin</name>   
+
            <name>Berlin</name>   
<description>Alexanderplatz, Berlin, Germany</description>   
+
            <description>Alexanderplatz, Berlin, Germany</description>   
<Point><coordinates>13.41156,52.526666</coordinates></Point>
+
            <Point>
</Placemark>
+
                  <coordinates>13.41156,52.526666</coordinates>
</Document>
+
            </Point>
 +
        </Placemark>
 +
    </Document>
 
</kml>
 
</kml>
 
</code>
 
</code>
  
 
==Example code==
 
==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 [[How to Obtain Your Own Nokia appID and Token| AppId and Token]] and replace http://my_domain.com/ at the end of the code the location of the HTML and KML files.
 +
<code javascript>
 +
<!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");
  
<code>
+
//
<html>
+
/////////////////////////////////////////////////////////////////////////////////////
<head>
+
            var map = new nokia.maps.map.Display(document.getElementById("map"),   
<script type="text/javascript" charset="UTF-8" src="http://api.maps.nokia.com/2.0.0/jsl.js?kml=auto"></script>
+
                  {    components: [ new nokia.maps.map.component.Behavior(),                 
</head>
+
<body>
+
<div id="map" style="width:100%; height:100%;"></div>
+
<script type="text/javascript">
+
 
+
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.ZoomBar(),                 
 
                       new nokia.maps.map.component.Overview(),                                             
 
                       new nokia.maps.map.component.Overview(),                                             
Line 68: Line 124:
 
                       new nokia.maps.map.component.ScaleBar(),                 
 
                       new nokia.maps.map.component.ScaleBar(),                 
 
                       new nokia.maps.map.component.InfoBubbles()],                               
 
                       new nokia.maps.map.component.InfoBubbles()],                               
            'zoomLevel': 4,        'center':[53.1, 13.1]});
+
                'zoomLevel': 4,         
 +
                'center':[53.1, 13.1]});
  
var kml = new nokia.maps.kml.Manager(),   
+
var kml = new nokia.maps.kml.Manager();
    resultSet, container;// Create a callback function for parsing the KML file
+
// We define a callback function for parsing kml file,
 
+
// and then push the parsing result to map display
// then push the parsing result to map display:
+
var onParsed = function (kmlManager) {
var onParsed = function (kmlManager)
+
var resultSet;
{
+
 
+
// KML file was successfully loaded
// Check if the parsing was successfully finished:   
+
if (kmlManager.state == "finished") {
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 all OK, go ahead and parse the KML file by KMLResultSet:       
+
if (resultSet.state == "finished") {
resultSet = new nokia.maps.kml.component.KMLResultSet(kmlManager.kmlDocument, map);      
+
// Retrieve map objects container from KML resultSet
container = resultSet.container;
+
container = resultSet.container;
 
+
// Push map objects & container to the map Display:       
+
// Add the container to the map's object collection so they will be rendered onto the map.
map.objects.add(container);
+
map.objects.add(container);
 
+
// Zoom the map to cover the area, uncomment this if you want.
+
// Switch the viewport of the map do show all KML map objects within the container
//        map.zoomTo(container.getBoundingBox());  
+
map.zoomTo(container.getBoundingBox());
 
+
}
}};
+
});
 
+
resultSet.create();
// Add an observer to the KML Manager 
+
}
kml.addObserver("state", onParsed);
+
};
 +
// Add an observer to kml manager
 +
kml.addObserver("state", onParsed);
  
 +
/////////////////////////////////////////////////////////////////////////////////////
 
// Start parsing a kml file with given url
 
// Start parsing a kml file with given url
// Note: Modify the URL / local file path according to your implementation.
+
// 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>
  
kml.parseKML("http://my_domain.com/" + "kml_data_file.kml");//
 
 
</script>
 
</body>
 
</html>
 
 
</code>
 
</code>
 
  
 
==See this example online here==
 
==See this example online here==
  
http://mapswidgets.com
+
http://mapswidgets.com/
  
 
==Geodetic reference systems in KML==
 
==Geodetic reference systems in KML==
Line 119: Line 179:
 
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]
 
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 Nokia Maps API==
+
==For more on the Nokia Maps API==
  
 
Please check out the Nokia Maps API full documentation and API reference here:
 
Please check out the Nokia Maps API full documentation and API reference here:
 +
* [http://developer.here.net/javascript_api Nokia Maps API]
  
http://api.maps.nokia.com==
+
You may also access the interactive API explorer
 +
* [http://developer.here.net/javascript_api_explorer API explorer]
  
 
==Tested with==
 
==Tested with==
  
Google Chrome: 14.0.835.202 m
+
Google Chrome: 20x
Mozilla Firefox 8.0
+
Mozilla Firefox 12.0
O/S Windows XP Professional 32bit
+

Revision as of 14:29, 14 March 2013

Article Metadata
Tested with
Devices(s): Internet Explorer, Firefox, Google Chrome, Opera
Compatibility
Platform(s): Web browser
Dependencies: Nokia Maps 2.2.4
Article
Keywords: Nokia Maps, JavaScript, KML
Created: Maveric (27 Oct 2011)
Updated: jasfox (10 Feb 2012)
Last edited: jasfox (14 Mar 2013)

Contents

Introduction

Nokia Maps API version 2.2.4 offers support for KML data formatted files and displaying the containing data on the Nokia Maps. This article will offer an overview to KML, structure and how it can be used within Nokia Maps.

Summary

Nokia 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

Nokia 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 Nokia Maps API.

Restrictions in Nokia Maps

Nokia Maps API does not currently support 3D so, these values if provided would be discarded by the API.- Nokia 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

Warning.pngWarning: 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 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")
and both the HTML and the kml_data_file.kml should be placed on http://my_domain.com/

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

http://mapswidgets.com/

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 Nokia Maps API

Please check out the Nokia 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

569 page views in the last 30 days.
×