The Basics

Google Maps API Tutorial

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 yourbrowser’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 http://www.google.com where the page was loaded from, not from the domain that your KML file came from.
Advertisements

The Basics

Google Maps API Tutorial

Google Earth Icons

The Google Earth icons are now available on the Google Maps server (so that Google Maps can render KML files that use them). There are four folders of icons

Each of the folders contains 64 icons (some of which are duplicates) named icon0.png to icon64.png

For each icon there’s a main icon image PNG (32 x 32) and a shadow image PNG (59 x 32) in the same folder.
No suitable transparent images, print images or imageMaps seem to be available.

 icon27.png  icon27s.png

These settings are suitable for most of the Google Earth icons:

   Icon.iconSize=new GSize(32,32);
   Icon.shadowSize=new GSize(56,32);
   Icon.iconAnchor=new GPoint(16,32);
   Icon.infoWindowAnchor=new GPoint(16,0);

Here’s an example

Pal2

icon0.png icon1.png icon2.png icon3.png icon4.png icon5.png icon6.png icon7.png
icon8.png icon9.png icon10.png icon11.png icon12.png icon13.png icon14.png icon15.png
icon16.png icon17.png icon18.png icon19.png icon20.png icon21.png icon22.png icon23.png
icon24.png icon25.png icon26.png icon27.png icon28.png icon29.png icon30.png icon31.png
icon32.png icon33.png icon34.png icon35.png icon36.png icon37.png icon38.png icon39.png
icon40.png icon41.png icon42.png icon43.png icon44.png icon45.png icon46.png icon47.png
icon48.png icon49.png icon50.png icon51.png icon52.png icon53.png icon54.png icon55.png
icon56.png icon57.png icon58.png icon59.png icon60.png icon61.png icon62.png icon63.png

Pal3

icon0.png icon1.png icon2.png icon3.png icon4.png icon5.png icon6.png icon7.png
icon8.png icon9.png icon10.png icon11.png icon12.png icon13.png icon14.png icon15.png
icon16.png icon17.png icon18.png icon19.png icon20.png icon21.png icon22.png icon23.png
icon24.png icon25.png icon26.png icon27.png icon28.png icon29.png icon30.png icon31.png
icon32.png icon33.png icon34.png icon35.png icon36.png icon37.png icon38.png icon39.png
icon40.png icon41.png icon42.png icon43.png icon44.png icon45.png icon46.png icon47.png
icon48.png icon49.png icon50.png icon51.png icon52.png icon53.png icon54.png icon55.png
icon56.png icon57.png icon58.png icon59.png icon60.png icon61.png icon62.png icon63.png

Pal4

icon0.png icon1.png icon2.png icon3.png icon4.png icon5.png icon6.png icon7.png
icon8.png icon9.png icon10.png icon11.png icon12.png icon13.png icon14.png icon15.png
icon16.png icon17.png icon18.png icon19.png icon20.png icon21.png icon22.png icon23.png
icon24.png icon25.png icon26.png icon27.png icon28.png icon29.png icon30.png icon31.png
icon32.png icon33.png icon34.png icon35.png icon36.png icon37.png icon38.png icon39.png
icon40.png icon41.png icon42.png icon43.png icon44.png icon45.png icon46.png icon47.png
icon48.png icon49.png icon50.png icon51.png icon52.png icon53.png icon54.png icon55.png
icon56.png icon57.png icon58.png icon59.png icon60.png icon61.png icon62.png icon63.png

Pal5

icon0.png icon1.png icon2.png icon3.png icon4.png icon5.png icon6.png icon7.png
icon8.png icon9.png icon10.png icon11.png icon12.png icon13.png icon14.png icon15.png
icon16.png icon17.png icon18.png icon19.png icon20.png icon21.png icon22.png icon23.png
icon24.png icon25.png icon26.png icon27.png icon28.png icon29.png icon30.png icon31.png
icon32.png icon33.png icon34.png icon35.png icon36.png icon37.png icon38.png icon39.png
icon40.png icon41.png icon42.png icon43.png icon44.png icon45.png icon46.png icon47.png
icon48.png icon49.png icon50.png icon51.png icon52.png icon53.png icon54.png icon55.png
icon56.png icon57.png icon58.png icon59.png icon60.png icon61.png icon62.png icon63.png