Starting ArcGIS JavaScript API: KMLLayers
KML or Keyhole Markup Language is an XML data structure for storing geographic information. The format was made popular by Google when they acquired Keyhole in 2004 and used it as their de facto file type for geographic data storage for use with their mapping products. It is now a OGC standard.
What does KML look like?
Below we can examine a snippet of KML (thanks Wikipedia!). At the first line it is possible to see how the markup starts with standard XML tags. The second line defines the markup as being KML. On line 4 we then define a 'Placemark' with child nodes defining things like the place name and description. Google use Placemarks as very simple markers for positioning a data point on a map. The default symbology is a yellow pin. If we jump to line 7, we can it is possible to see where we explicitly state that this is a Point geometry with the coordinates coming as a child node (line 😎 of this.
<?xml version="1.0" encoding="UTF-8"?> <kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <Placemark> <name>New York City</name> <description>New York City</description> <Point> <coordinates>-74.006393,40.714172,0</coordinates> </Point> </Placemark> </Document> </kml>
How can we use KML in our ArcGIS JavaScript app?
The ArcGIS JavaScript API provides a module for dealing with KML files: KMLLayer. KMLLayer allows us to provide a URL to a public facing KML file and use that geographic data in our ArcGIS JavaScript app. Indeed because of the nature of KML the API actually turns the KML into a series of Feature Layers using a ArcGIS service, so its easier to think of the KMLLayer as a group of layers as opposed to one homogeneous layer.
The KMLLayer converts the KML file down into one of three feature layers; one for points, one for lines and one for polygons. For most intents and purposes you can use a KML layer like you would any other Feature Layer. For example you can query them and use them in geoprocessing tasks.
It is important to note that we must use explicit absolute path names to our KML file to for the KMLLayer to work! This is because the file path gets sent to a utility service to process the KML into the returned Feature Layers.
A Hello World Example
require([
"esri/map",
"esri/layers/KMLLayer",
"dojo/domReady!"
],
function(Map, KMLLayer, PictureMarkerSymbol, SimpleRenderer) {
var map = new Map("map", {
basemap: "gray",
center: [0, 30], // longitude, latitude
zoom: 4
});
// A KML Layer: We must explicitly state the full URL (relative URLs will throw errors!)
var layer = new KMLLayer("http://www.loxodrome.io/demos/kmllayers/samplekml.kml", { });
layer.on("load", function() {
var layers = layer.getLayers()
console.log(layers);
});
map.addLayer(layer); // Add the layer to the map
});
Here we create a KMLLayer (line 16) and then wait for it to return the relative Feature Layers from the utility service. We then use the .on method for wait for it to have loaded and console log it's layers (line 18). This demonstrates how we can quite simply take a KML url and have a layer on the map in a few lines of code. The KMLLayer will also maintain symbology and attributes.
How can I use firewalled KML files?
You will need to use your own utility service which requires Portal for ArcGIS. After this you can configure your JavaScript to use the service:
require(["esri/config"], function(esriConfig) {
esriConfig.defaults.kmlService = "http://servername.domain.suffix/arcgis/sharing/kml";
});KML Samples: