Revision as of 19:40, 18 January 2012 by jasfox (Talk | contribs)

HERE Maps API - Converting any data file to KML

From Nokia Developer Wiki
Jump to: navigation, search

Underconstruction.pngUnder Construction: (20120118141431) This article is under construction and it may have outstanding issues. If you have any comments please use the comments tab.

This article explains how to read address data from an arbitrary file format, and create a KML file for display on a map.

Note.pngNote: in order to load a KML file successfully, the generated 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 example, if you are hosting at example.com, the final line of the JavaScript to load the KML will need to be:

kml.parseKML("http://example.com/" + "generated_kml_data_file.kml")
and both the KML loading HTML and the generated_kml_data_file.kml should be placed on http://example.com/

Article Metadata
Code ExampleTested with
Devices(s): Firefox 9.0.1
Platform(s): Web Browser
Keywords: Nokia Maps, JavaScript, KML
Created: jasfox (18 Jan 2012)
Last edited: jasfox (18 Jan 2012)


Keyhole Markup Language (KML) is an XML notation for geographic applications. The advantages of using KML are numerous, and have been listed in a previous article. A typical enterprise may wish to add some markers representing addresses onto a map for their website, but without necessarily learning too much about geocoding or KML. It is likely that the address data they have is already held in a file or spreadsheet somewhere.

This example aims to take the pain out of creating a KML dataset. It aims to take any data format and attempt to the locate addresses given by specified fields from the file. The addresses are then transformed into KML <Placemarks> with associated <name> and <description> elements taken from other fields from the same record. The generated KML data can be inspected and edited using the editor example given here and then displayed using the code from the How to display KML data example. In summary, this article demonstrates a real world use of the geocoding service and is an example of making sequential asynchronous JavaScript calls to obtain longitude and latitude.

Defining the issue

For a typical data file, the first line in the file will be a header line which defines the fields in the records below. Each field will be separated from the next by some arbitrary separator character. For a CSV file for example, the separator character will be a comma (,) for other data formats it may be a space( ), a pipe (|) or some other character. At the end of the header line there will be some form of terminating character (typically a new line). Thereafter each subsequent line of data will hold a record of separated fields of data, with each field being associated to the definition of the field held in the header.

For example the following spreadsheet

serial name unused address_street address_city address_district description
13556 Millenium Stage Something 401 Bay Drive New York This is an example
3243 The Chambers Something else 53 Bothwell Street Watford Hertfordshire Some more text here
9954 4th Dimension More data 226 Myrtle Ave Toronto
8645 E.K.B.R. Even more data Invalidenstrasse 117 Berlin Hier gibts etwas

could be written out as a CSV file in the following format:

 serial, name , unused,address_street, address_city, address_district, description
13556, Millenium Stage, Something, 401 Bay Drive,New York, This is an example
3243, The Chambers, Something else, 53 Bothwell Street, Watford,Hertfordshire, Some more text here
9954, 4th Dimension, More data, 226 Myrtle Ave , Toronto,,
8645, E.K.B.R, Even more data, Invalidenstrasse 117, Berlin,, Hier gibts etwas

The problem comes in several parts:

  • Deciding where the header line starts - in the case above, there is no preamble, but potentially the data could have a prefix or some white space before it.
  • Deciding what the field and line terminators are
  • Deciding where the data starts - in the case above, again there is no premable, but potentially there could be a gao between the data and the header.
  • Deciding which fields are needed in the KML
  • Deciding which fields form the address to geocode.
  • Deciding what do do if the geocoding fails.

   // Set up variables for later use
// These varibales will define which fields are extracted from the data.
var headerStart ;
var dataStart;
var lineSep;
var fieldSep;
var addressFields;
var descriptionFields;
var nameFields ;
var idField;
var styleURLFields;
// These variables will hold the data for the current record being processed
var id ="";
var data;
var headers;
var address = "";
var name = "";
var description = "";
var styleURL = "";
// We need to keep a count of which record we are processing, and if we are
// trying a fallback geocoding option.
var addressingAttempt = 0;
var currentRecord = 0;
// Search Manager taken directly from playground examples.
var searchManager = new nokia.maps.search.Manager();
searchManager.addObserver("state", function (observedManager, key, value) {
// If the search has finished we can process the result.
if (value == "finished") {
// We check that at least one location has been found
if (observedManager.locations.length > 0) {
var markerData = new Object();
// Since we have an address we can add the current data to the map
// as the addressing data has been found to be valid.
markerData.coords = observedManager.locations[0].displayPosition;
markerData.id = id;
markerData.title = map.objects.getLength() + 1;
markerData.description = description.trim();
markerData.name = name.trim();
markerData.address = address.trim();
markerData.styleURL = styleURL.trim();
// Center on the new marker and start to process the next record.
addressingAttempt = 0;
lat.innerHTML= "Found: " + address;
} else {
// Try again with geocoding the same data, using alternate fields
// to define the address.
lat.innerHTML= "Not Found: " + address;
if (addressingAttempt == addressFields.length){
// There are no more fall back addressing options.
// Move on to the next record regardless.
addressingAttempt = 0;
// Find the next address, either a new record or using new address fields.
} else if (value == "failed") {
// Geocoding has failed.
lat.innerHTML = "The search request failed.";
// set up the map in the usyual manner.
var map = new nokia.maps.map.Display(document.getElementById("map"), {
'components': [
//behavior collection
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() ],
'zoomLevel': 12, //zoom level for the map
'center': [52.51, 13.4] //center coordinates
// This will display the data from the description as HTML
var infoBubbles = new nokia.maps.map.component.InfoBubbles();
infoBubbles.options.defaultWidth = 200;
map.addComponent( infoBubbles);
// Decide which fields are to be placed in which part of the KML.
// Split the header from the data and process each record in turn.
function doSplit (){
var dataInput = document.getElementById('dataInput').value;
headerStart = document.getElementById('headerStart').value; //"#DEFINITION#\n" for Right Move.
headerStart = headerStart.replace("\\n", "\n").replace("\\n", "\n"); // Convert up to two \n into carriage returns
dataStart = document.getElementById('dataStart').value; // "#DATA#\n" for Right Move.
dataStart = dataStart.replace("\\n", "\n").replace("\\n", "\n"); // Convert up to two \n into carriage returns
lineSep = document.getElementById('lineSep').value;// ; "|\n\n" for Right Move.
lineSep = lineSep.replace("\\n", "\n").replace("\\n", "\n"); // Convert up to two \n into carriage returns
fieldSep = document.getElementById('fieldSep').value;
addressFields = new Array();
// Each of these address strategies will be tried in turn.
// Any fields added here will be appended to the <address> element.
descriptionFields = document.getElementById('descriptionFields').value.split(fieldSep);
// Any fields added here will be appended to the <name> element.
nameFields = document.getElementById('nameFields').value.split(fieldSep);
// This field will be the id of the <Placemark> element.
idField = document.getElementById('idField').value;
// These fields will make up the <styleURL> of the <Placemark>
styleURLFields = document.getElementById('styleURLFields').value.split(fieldSep);
if (headerStart != ""){
// Remove any pre-amble before the header record.
var from = dataInput.search (headerStart) + headerStart.length;
dataInput = dataInput.substr(from);
data = dataInput.split (lineSep);
headers = data[0].split(fieldSep);
if (dataStart != ""){
// Remove any preable prior to the first data record.
var from = dataInput.search (dataStart) + dataStart.length;
dataInput = dataInput.substr(from);
data = dataInput.split (lineSep);
// Find the FIRST address. The next one will be chained from the
// search manager.
currentRecord = 0;
addressingAttempt = 0;
// Standard Library for spliting up Comma Delimited Texts.
String.prototype.splitCSV = function(sep) {
for (var foo = this.split(sep = sep || ","), x = foo.length - 1, tl; x >= 0; x--) {
if (foo[x].replace(/"\s+$/, '"').charAt(foo[x].length - 1) == '"') {
if ((tl = foo[x].replace(/^\s+"/, '"')).length > 1 && tl.charAt(0) == '"') {
foo[x] = foo[x].replace(/^\s*"|"\s*$/g, '').replace(/""/g, '"');
} else if (x) {
foo.splice(x - 1, 2, [foo[x - 1], foo[x]].join(sep));
} else foo = foo.shift().split(sep).concat(foo);
} else foo[x].replace(/""/g, '"');
return foo;
// Obtains the Longitude and Latitude of the next record
// Based upon the data in the chosen fields of that recod.
function doNextGeoCode(){
if (currentRecord < data.length){
var fields = data[currentRecord].splitCSV(fieldSep);
// Clear all the current data.
id = "";
address = "";
description = "";
name = "";
styleURL = "";
// Loop through the fields and append them to the address,
// description, name etc.
for (var i = 0; i <fields.length ; i++){
if (isAddressField(headers[i])){
address = address + fields[i] + " ";
if( isDescriptionField ( headers[i])){
description = description + fields[i] + " ";
if( isNameField ( headers[i])){
name = name + fields[i] + " ";
if (isIdField ( headers[i])){
id = fields[i];
if (isStyleURLField (headers[i])){
styleURL = styleURL + fields[i];
// Assuming we have an address to try, we should geocode it.
if (address != "" ){
} else {
// Otherwise we need to try another addressing strategy.
if (addressingAttempt == addressFields.length){
// Since we have run out of addressing strategies,
// try the next record.
addressingAttempt = 0;
function isAddressField ( field ){
for (var addFieldCount = 0; addFieldCount <addressFields[addressingAttempt].length ; addFieldCount++){
if (field == addressFields[addressingAttempt][addFieldCount]){
return true;
return false;
function isDescriptionField ( field){
for (var descFieldCount = 0; descFieldCount < descriptionFields.length ; descFieldCount++){
if (field == descriptionFields[descFieldCount]){
return true;
return false;
function isNameField ( field){
for (var nameFieldCount = 0; nameFieldCount < nameFields.length ; nameFieldCount++){
if (field == nameFields[nameFieldCount]){
return true;
return false;
function isIdField ( field){
if (field == idField){
return true;
return false;
function isStyleURLField ( field ){
for (var styleURLFieldCount = 0; styleURLFieldCount <styleURLFields.length ; styleURLFieldCount++){
if (field == styleURLFields[styleURLFieldCount]){
return true;
return false;


Add categories below. Remove Category:Draft when the page is complete or near complete

206 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.


Thank you!

We appreciate your feedback.