Technical Overview: KML

KML (Keyhole Markup Language) was developed by Keyhole, Inc for adding geographic annotation, models, and simple animation to their Keyhole Earth Viewer. Keyhole was taken over by Google in 2004, and the Earth Viewer is now known as Google Earth. Google have also adopted it for use on their Google Maps platform, and it is quickly becoming the de facto standard for geographic annotation.

KML is based on XML (eXtensible Markup Language) and is relative compact. This makes it easy to use and to learn. With the widespread use of XML, reading and writing most KML entities is not difficult.

Here is a simple example taken from the maps at This project used OpenLayers to display a number of KML layers. Here is a subset of the “plants” layer displayed in Google Earth:

Example KML shapes in Google Earth

Google Earth coverage of rural Costa Rica is limited, but this image shows the basic concept. Here is the subset of the “plants” layer that created the above image:


A KML file consists of a Document entity which contains the required shapes. These shapes are referred to as Placemarks. A placemark has a name, description, and style. Althought they are often thought of as pushpins (points), they can also be lines, polgyons (as above), and 3d models using the COLLADA format. Placemark geometries can also be defined as with a ‘MultiGeometry’ entity, to define the placemark with multiple shapes. For example, a farm could be defined with a property boundary (polygon) and a house (point).

The above example defines two named styles to represent two different kinds of plantation (plant_mixed, plant_mono). This is the usual method of applying styles, but it is also possible to define a style locally within a placemark definition. It is also possible to define styles in an external KML file by giving the full URL in the styleUrl tag.

Placemarks can also be defined in 3d by giving them an altitude. This can be defined relative to sea level or terrain height, and it can be ‘extruded’ to give it thickness.

Placemark descriptions can include standard XHTML, but these should be enclosed with CDATA tags. Key/value data can be included in extension tags. For example, a map of cinemas might include extension tags for the owner, number of screens, and number of seats.

Viewpoints can also be defined in 3D. They can be specified for particular features (LookAt element) or as general viewpoints (Camera element).

KML files can also import images, both as ground overlays (eg. an aerial photograph) or as a photograph (eg. a ‘digital billboard’). As well as being flat, photographs can be defined as cylinders. Cylindrical photographs can provide simple but effective backdrops for 3D models.

Time stamps or time spans can be applied to features, allowing for simple animations. For example, a hiker’s progress could be marked with multiple time-stamped placemarks.

Areas of the map can be defined as regions using the Region element. These can be set to appear for specific scales. For example, complex 3D models or areas of dense placemarks could be set to only appear at high zoom levels. When zoomed out, these could be replaced with simpler representations. This reduces clutter and speeds rendering times.

It should be apparant that KML is a very powerful language, especially for 3D geographic browsers such as Google Earth. However it does have some limitations. Although it is becoming a standard for geographic annotation, most of these viewers are 2D viewers. These simply cannot render 3D models or provide a good representation of altitude. Other aspects of the standard (eg. animation) are often not supported. Finally, KML is an annotation language. It is great for drawing shapes, bitmaps, and models on existing maps. It does not offer the model richness required to define a complete map. Instead, a standard such as GML or ESRI Shape should be chosen instead.

Leave a Reply