Google Maps API Tutorial

© 2006, 2007, 2008, 2009 Mike Williams

 
Translate this page:

 

Sending KML files to Google Maps

Instead of developing your own page with Google Maps API, it's possible to write a KML file and send it to Google Maps.

Google Maps understands a small subset of KML 2.0, and implements markers, polylines, polygons, info windows and a sidebar.

A simple KML file contains an XML header, a KML header and a <Document>...</Document> structure. That <Document> can contain a series of <Placemark>s which each describe one marker or polyline.

Here's what a basic XML file looks like

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.0">
<Document>
  <name>KML Example file</name>
  <description>Simple markers</description>

  <Placemark>
    <name>Marker 1</name>
    <description>Some stuff to put in the first info window</description>
    <Point>
      <coordinates>-122.1,37.4,0</coordinates>
    </Point>
  </Placemark>

</Document>
</kml>
The whole file must be syntactically valid XML. The case of the tags is significant.
The Document name is displayed in the title bar and in bold in the sidebar.
The Document description is displayed in the sidebar.
The Placemark name is displayed in the sidebar and in bold in the info window.
The Placemark description is displayed in the info window.
The coordinates are in the order longitude, latitude, altitude. (Note that this is the opposite order from GLatLng() in the Google Maps API) The altitude value is not used.
The map will be automatically centred and zoomed in such a way as to contain all the placemarks.

To send the KML file to Google Maps, put its full URL in the ?q parameter, like this http://maps.google.com/maps?q=http://econym.org.uk/gmap/example1.kml

Marker Icons

That example used the default marker icons. As an alternative you can use the Google Earth icons.
  <Placemark>

    <Style>
      <IconStyle>
        <Icon>
          <href>root://icons/palette-3.png</href>
          <x>64</x>
          <y>32</y>
          <w>32</w>
          <h>32</h>
        </Icon>
      </IconStyle>
    </Style>

    <name>Marker 1</name>
    <description>Some stuff to put in the first info window</description>
    <Point>
      <coordinates>-122.1,37.4,0</coordinates>
    </Point>
  </Placemark>
The <Style>, <IconStyle> and <Icon> tags should be nested as shown.
The <href> indicates which of the four Google Earth palettes the icon is chosen from.
The available palettes are numbered 2, 3, 4 and 5.
The <x> and <y> values indicate the position of the icon within the palette.
Only the values 0, 32, 64, 96, 128, 160, 192 and 224 are permitted.
The <h> and <w> values indicate the size of the icon. The values must always be 32.

The four palettes, eight x values and eight y values allow any of the 256 Google Earth icons to be selected.

Here's an example

Custom Icons

It is now possible to use your own custom icon images. The images must be on a webserver that the Google server can read, not on your own local disk.
  <Placemark>

    <Style>
      <IconStyle>
        <Icon>
          <href>http://www.domain.com/images/mymarker.png</href>
        </Icon>
      </IconStyle>
    </Style>

Polylines

A polyline can be drawn with the <LineString> Placemark, like this:
  <Placemark>
    <name>Polyline 1</name>
    <description>This is some info about polyline 1</description>

    <Style>
      <LineStyle>
        <color>ff00ff00</color>
        <width>6</width>
      </LineStyle>
    </Style>

    <LineString>
      <coordinates>-122.1,37.4,0 -122.0,37.4,0 -122.0,37.5,0 -122.1,37.5,0 -122.1,37.4,0</coordinates>
    </LineString>
  </Placemark>
Like Point Placemarks, there will be a clickable entry in the sidebar for each LineString Placemark.
The <Style> section is optional. If omitted you get the default polyline style.
The <color> is specified with eight hexadecimal characters, which consists of four pairs. In turn they represent Opacity, Blue, Green and Red.
Here's an example

Polygons

A filled polyfon can be drawn with the <Multigeometry><Polygon> Placemark, like this:
  <Placemark>
    <name>Polygon 1</name>
    <description>This is some info aboout polygon 1</description>

    <Style>
      <PolyStyle>
        <color>44ff0000</color>
        <fill>1</fill>
        <outline>1</outline>
      </PolyStyle>
    </Style>

    <MultiGeometry>
      <Polygon>
        <outerBoundaryIs>
          <LinearRing>
            <coordinates>-122.1,37.4,0 -122.0,37.4,0 -122.0,37.5,0 -122.1,37.5,0 -122.1,37.4,0</coordinates>
          </LinearRing>
        </outerBoundaryIs>
      </Polygon>
    </MultiGeometry>

  </Placemark>
Like Point Placemarks, there will be a clickable entry in the sidebar for each LineString Placemark.
The <Style><PolyStyle> section is optional. If omitted you get the default polygon style.
Here's an example

HTML descriptions

A subset of HTML is permitted in the <description> fields. This allows you to insert links and images in the sidebar and info windows.

When doing so, you should use <![CDATA[ ]]> to prevent the contents being interpreted as XML .

  <description><![CDATA[  <a href="http://www.econym.demon.co.uk">Clickable Link</a>  ]]></description>
<span>s and <div>s don't seem to be accepted.

Here's an example

Potential Pitfalls

  1. Watch out for the order of the <coordinates> parameters: longitude then latitude.
     
  2. If you make a change to your KML file, the old copy will be cached on the Google server for a while. Refreshing your browser's cache won't force Google to refresh their cache. What you can do is to temporarily add an arbitrary parameter to the end of the url, like "?123", to make the Google cache think that it's different.
     
  3. KML files can't be sent from your local disk with URLs that begin with "file://" they need to be on a real web server.
     
  4. If you use an image, or any other resource, in your <description> fields, you must use the full URL.
     
    Relative URLs are considered to refer to files on www.google.com where the page was loaded from, not from the domain that your KML file came from.

Back to Mike's Homepage
Up to the start of this tutorial