You're all set!

To start developing, please head over to our developer documentation.

Activate the Google Maps JavaScript API

To get you started we'll guide you through the Google Developers Console to do a few things first:

  1. Create or choose a project
  2. Activate the Google Maps JavaScript API and related services
  3. Create appropriate keys
Continue

KML and GeoRSS Layers

The KmlLayer renders KML and GeoRSS elements into a Google Maps JavaScript API tile overlay.

Overview

The Google Maps JavaScript 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.

The Maps JavaScript API converts the provided geographic XML data into a KML representation which is displayed on the map using a Maps JavaScript API tile overlay. This KML looks (and somewhat behaves) like familiar Maps JavaScript API 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 JavaScript 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:

  • map specifies the Map on which to render the KmlLayer. You can hide a KmlLayer by setting this value to null within the setMap() method.
  • preserveViewport specifies that the map should not be adjusted to the bounds of the KmlLayer’s contents when showing the layer. By default, when displaying a KmlLayer, the map is zoomed and positioned to show the entirety of the layer’s contents.
  • suppressInfoWindows indicates that clickable features within the KmlLayer should not trigger the display of InfoWindow objects.

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 initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 49.496675, lng: -102.65625}
  });

  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);
}
<div id="map"></div>
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 49.496675, lng: -102.65625}
  });

  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);
}

View GeoRSS example

The following example constructs a KmlLayer from the given KML feed:

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 41.876, lng: -87.624}
  });

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}
<div id="map"></div>
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 41.876, lng: -87.624}
  });

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}

View KML example

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 JavaScript 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:

  • position indicates the latitude/longitude coordinates at which to anchor the InfoWindow for this KML feature. This position is generally the clicked location for polygons, polylines, and GroundOverlays, but the true origin for markers.
  • pixelOffset indicates the offset from the above position to anchor the InfoWindow “tail.” For polygonal objects, this offset is typically 0,0 but for markers includes the height of the marker.
  • featureData contains a JSON structure of KmlFeatureData.

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 initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: {lat: 37.06, lng: -95.68}
  });

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/kml-samples/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}
<div id="map"></div>
<div id="content-window"></div>
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  float: left;
  height: 100%;
  width: 79%;
}
#content-window {
  float: left;
  font-family: 'Roboto','sans-serif';
  height: 100%;
  line-height: 30px;
  padding-left: 10px;
  width: 19%;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: {lat: 37.06, lng: -95.68}
  });

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/kml-samples/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}

View KML example

Size and complexity restrictions for KML rendering

The Google Maps JavaScript API has limitations to the size and complexity of loaded KML files. Below is a summary of the current limits.

Note: These limits are subject to change at any time.

Maximum fetched file size (raw KML, raw GeoRSS, or compressed KMZ)
3MB
Maximum uncompressed KML file size
10MB
Maximum number of network Links
10
Maximum number of total document-wide features
1,000
Number of KML layers
There is a limit on the number of KML Layers that can be displayed on a single Google Map. If you exceed this limit, none of your layers will appear on the map, and an error will be reported in your web browser's JavaScript console. The limit is based on a combination of the number of KMLLayer classes created and the total length of all the URLs used to create those layers. Each new KMLLayer you create will take up a portion of the limit for the layer and a further portion of the limit depending on the length of the URL where the KML file was loaded from. Consequently, the number of layers you can add will vary by application; on average, you should be able to load between 10 and 20 layers without hitting the limit. If you still hit the limit, use a URL shortner (such as https://goo.gl) to shorten the KML URLs. Alternatively, create a single KML file consisting of NetworkLinks to the individual KML URLs.

Supported KML elements

The Google Maps JavaScript API supports the following KML elements. The KML parser generally silently ignores XML tags it does not understand.

  • Placemarks
  • Icons
  • Folders
  • Descriptive HTML—Entity replacement via <BalloonStyle> and <text>
  • KMZ (compressed KML, including attached images)
  • Polylines and polygons
  • Styles for polylines and polygons, including color, fill, and opacity
  • Network links to import data dynamically
  • Ground overlays and screen overlays

The following table gives full details of the supported KML elements.

KML element Supported in the API? Comment
<address> no
<AddressDetails> no
<Alias> N/A <Model> is not supported
<altitude> no
<altitudeMode> no
<atom:author> yes
<atom:link> yes
<atom:name> yes
<BalloonStyle> partially only <text> is supported
<begin> N/A <TimeSpan> is not supported
<bgColor> no
<bottomFov> N/A <PhotoOverlay> is not supported
<Camera> no
<Change> partially only style changes are supported
<color> partially includes #AABBGGRR and #BBGGRR; not supported in <IconStyle>, <ScreenOverlay>, and <GroundOverlay>
<colorMode> no
<cookie> no
<coordinates> yes
<Create> no
<Data> yes
<Delete> no
<description> yes HTML content is allowed but is sanitized to protect from cross-browser attacks. Entity replacements of the form $[dataName] are not supported.
<displayMode> no
<displayName> no
<Document> partially implicitly, children are supported; no effect as child of other Features
<drawOrder> no
<east> yes
<end> N/A <TimeSpan> is not supported
<expires> yes see Summary section for details
<ExtendedData> partially untyped <Data> only, no <SimpleData> or <Schema>, and entity replacements of the form $[dataName] are not supported.
<extrude> no
<fill> yes
<flyToView> no
<Folder> yes
<geomColor> no deprecated
<GeometryCollection> no deprecated
<geomScale> no deprecated
<gridOrigin> N/A <PhotoOverlay> is not supported
<GroundOverlay> yes cannot be rotated
<h> yes deprecated
<heading> yes
hint yes target=... supported
<hotSpot> yes
<href> yes
<httpQuery> no
<Icon> yes cannot be rotated
<IconStyle> yes
<ImagePyramid> N/A <PhotoOverlay> is not supported
<innerBoundaryIs> yes implicitly from <LinearRing> order
<ItemIcon> N/A <ListStyle> is not supported
<key> N/A <StyleMap> is not supported
<kml> yes
<labelColor> no deprecated
<LabelStyle> no
<latitude> yes
<LatLonAltBox> yes
<LatLonBox> yes
<leftFov> N/A <PhotoOverlay> is not supported
<LinearRing> yes
<LineString> yes
<LineStyle> yes
<Link> yes
<linkDescription> no
<linkName> no
<linkSnippet> no
<listItemType> N/A <ListStyle> is not supported
<ListStyle> no
<Location> N/A <Model> is not supported
<Lod> yes
<longitude> yes
<LookAt> no
<maxAltitude> yes
<maxFadeExtent> yes
<maxHeight> N/A <PhotoOverlay> is not supported
<maxLodPixels> yes
<maxSessionLength> no
<maxWidth> N/A <PhotoOverlay> is not supported
<message> no
<Metadata> no deprecated
<minAltitude> yes
<minFadeExtent> yes
<minLodPixels> yes
<minRefreshPeriod> no <NetworkLink>
<Model> no
<MultiGeometry> partially rendered but displayed as separate features in left side panel
<name> yes
<near> N/A <PhotoOverlay> is not supported
<NetworkLink> yes  
<NetworkLinkControl> partially <Update> and <expires> partially supported. The API ignores expiration settings in the HTTP headers but does use the expiration settings specified in KML. In the absence of expiration settings, or within the time validity interval, Google Maps may cache data fetched from the Internet for unspecified durations. A refetch of the data from the Internet can be forced by renaming the document and fetching it under a different URL, or by making sure that the document contains appropriate expiration settings.
<north> yes
<open> yes
<Orientation> N/A <Model> is not supported
<outerBoundaryIs> yes implicitly from <LinearRing> order
<outline> yes
<overlayXY> no
<Pair> N/A <StyleMap> is not supported
<phoneNumber> no
<PhotoOverlay> no
<Placemark> yes
<Point> yes
<Polygon> yes
<PolyStyle> yes
<range> yes
<refreshInterval> partially <Link> only; not in <Icon>
<refreshMode> yes HTTP headers not supported for "onExpire" mode. See notes on <Update> and <expires> above.
<refreshVisibility> no
<Region> yes
<ResourceMap> N/A <Model> is not supported
<rightFov> N/A <PhotoOverlay> is not supported
<roll> N/A <Camera> and <Model> are not supported
<rotation> no
<rotationXY> no
<Scale> N/A <Model> is not supported
<scale> no
<Schema> no
<SchemaData> no
<ScreenOverlay> yes cannot be rotated
<screenXY> no
<shape> N/A <PhotoOverlay> is not supported
<SimpleData> N/A <SchemaData> are not supported
<SimpleField> N/A <Schema> are not supported
<size> yes
<Snippet> yes
<south> yes
<state> N/A <ListStyle> is not supported
<Style> yes
<StyleMap> no rollover (highlight) effects are not supported
<styleUrl> N/A <StyleMap> is not supported
<targetHref> partially supported in <Update>, not in <Alias>
<tessellate> no
<text> yes replacement of $[geDirections] is not supported
<textColor> no
<tileSize> N/A <PhotoOverlay> is not supported
<tilt> no
<TimeSpan> no
<TimeStamp> no
<topFov> N/A <PhotoOverlay> is not supported
<Update> partially only style changes, not <Create> or <Delete>
<Url> yes deprecated
<value> yes
<viewBoundScale> no
<viewFormat> no
<viewRefreshMode> partially "onStop" is supported
<viewRefreshTime> yes
<ViewVolume> N/A <PhotoOverlay> is not supported
<visibility> partially yes on <Folder> - child placemarks inherit their visibility
<w> yes deprecated
<west> yes
<when> N/A <TimeStamp> is not supported
<width> yes
<x> yes deprecated
<y> yes deprecated

Send feedback about...

Google Maps JavaScript API
Google Maps JavaScript API
Need help? Visit our support page.