The KmlLayer renders KML and GeoRSS elements into a Maps API V3 tile overlay.
Overview
The Google Maps API supports the KML and GeoRSS data formats for displaying
geographic information. These data formats are displayed on a map using a
KmlLayer object, whose constructor takes the URL of a publicly accessible KML
or GeoRSS file.
Note: Please read the KML Support page in the KML documentation for information about supported elements and size and complexity restrictions.
The Maps API converts the provided geographic XML data into a KML
representation which is displayed on the map using a V3 tile overlay. This KML
looks (and somewhat behaves) like familiar V3 overlay elements. KML
<Placemark> and GeoRSS point elements are rendered as markers, for
example, <LineString> elements are rendered as polylines and
<Polygon> elements are rendered as polygons. Similarly,
<GroundOverlay> elements are rendered as rectangular images on the map.
Importantly, however, these objects are not Google Maps API Markers,
Polylines, Polygons or GroundOverlays; instead, they are rendered into a
single object on the map.
KmlLayer objects appear on a map once their map property has been set. You
can remove them from the map by calling setMap() passing null. The
KmlLayer object manages the rendering of these child elements by
automatically retrieving appropriate features for the map’s given bounds. As
the bounds change, features in the current viewport are automatically rendered.
Because the components within a KmlLayer are rendered on demand, the layer
allows you to easily manage the rendering of thousands of markers, polylines,
and polygons. Note that you can’t access these constituent objects directly,
though they each provide click events which return data on those individual
objects.
KML Layer Options
The KmlLayer() constructor optionally passes a number of KmlLayerOptions:
mapspecifies theMapon which to render theKmlLayer. You can hide aKmlLayerby setting this value tonullwithin thesetMap()method.preserveViewportspecifies that the map should not be adjusted to the bounds of theKmlLayer’s contents when showing the layer. By default, when displaying aKmlLayer, the map is zoomed and positioned to show the entirety of the layer’s contents.suppressInfoWindowsindicates that clickable features within theKmlLayershould not trigger the display ofInfoWindowobjects.
Additionally, once the KmlLayer is rendered, it contains an immutable
metadata property containing the layer’s name, description, snippet and author
within a KmlLayerMetadata object literal. You can inspect this information
using the getMetadata() method. Because rendering of KmlLayer objects
requires asynchronous communication to an external server, you will want to
listen for the metadata_changed event, which will indicate that the property
has been populated.
The following example constructs a KmlLayer from the given GeoRSS feed:
function initialize() {
var myLatlng = new google.maps.LatLng(49.496675,-102.65625);
var mapOptions = {
zoom: 4,
center: myLatlng
}
var map = new google.maps.Map(document.getElementById('map-canvas'), mapOptions);
var georssLayer = new google.maps.KmlLayer({
url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
});
georssLayer.setMap(map);
}
google.maps.event.addDomListener(window, 'load', initialize);
The following example constructs a KmlLayer from the given KML feed:
function initialize() {
var chicago = new google.maps.LatLng(41.875696,-87.624207);
var mapOptions = {
zoom: 11,
center: chicago
}
var map = new google.maps.Map(document.getElementById('map-canvas'), mapOptions);
var ctaLayer = new google.maps.KmlLayer({
url: 'http://gmaps-samples.googlecode.com/svn/trunk/ggeoxml/cta.kml'
});
ctaLayer.setMap(map);
}
google.maps.event.addDomListener(window, 'load', initialize);
KML Feature Details
Because KML may include a large number of features, you may not access feature
data from the KmlLayer object directly. Instead, as features are displayed,
they are rendered to look like clickable Maps API overlays. Clicking on
individual features, by default, brings up an InfoWindow containing KML
<title> and <description> information on the given feature.
Additionally, a click on a KML feature generates a KmlMouseEvent, which passes
the following information:
positionindicates the latitude/longitude coordinates at which to anchor theInfoWindowfor this KML feature. This position is generally the clicked location for polygons, polylines, and GroundOverlays, but the true origin for markers.pixelOffsetindicates the offset from the abovepositionto anchor theInfoWindow“tail.” For polygonal objects, this offset is typically0,0but for markers includes the height of the marker.featureDatacontains a JSON structure ofKmlFeatureData.
A sample KmlFeatureData object is shown below:
{
author: {
email: "nobody@google.com",
name: "Mr Nobody",
uri: "http://example.com"
},
description: "description",
id: "id",
infoWindowHtml: "html",
name: "name",
snippet: "snippet"
}
The following example displays KML feature <Description> text within a
side <div> when the feature is clicked:
function initialize() {
var myLatlng = new google.maps.LatLng(37.06, -95.68);
var mapOptions = {
zoom: 12,
center: myLatlng
};
var map = new google.maps.Map(document.getElementById('map-canvas'),
mapOptions);
var kmlLayer = new google.maps.KmlLayer({
url: 'http://kml-samples.googlecode.com/svn/trunk/kml/Placemark/placemark.kml',
suppressInfoWindows: true,
map: map
});
google.maps.event.addListener(kmlLayer, 'click', function(kmlEvent) {
var text = kmlEvent.featureData.description;
showInContentWindow(text);
});
function showInContentWindow(text) {
var sidediv = document.getElementById('content-window');
sidediv.innerHTML = text;
}
}
google.maps.event.addDomListener(window, 'load', initialize);