KML Tutorial
KML Tutorial
Table of Contents
1. Basic KML Documents
1. Placemarks
2. Descriptive HTML in Placemarks
3. Ground Overlays
4. Paths
5. Polygons
2. Advanced KML Documents
1. Styles for Geometry
2. Styles for Highlighted Icons
3. Screen Overlays
4. Network Links
3. KML MIME Types
Placemarks
A Placemark is one of the most commonly used features in Google Earth. It marks a position on the
Earth's surface, using a yellow pushpin as the icon. The simplest Placemark includes only a <Point>
element, which specifies the location of the Placemark. You can specify a name and a custom icon for
the Placemark, and you can also add other geometry elements to it.
Open the KML Samples file in Google Earth and expand the Placemarks subfolder. This folder includes
three different types of placemark: simple, floating, and extruded. The KML code for the simple
placemark looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Placemark>
<name>Simple placemark</name>
<description>Attached to the ground. Intelligently places itself
at the height of the underlying terrain.</description>
<Point>
<coordinates>-122.0822035425683,37.42228990140251,0</coordinates>
</Point>
</Placemark>
</kml>
<coordinates>102.595626,14.996729</coordinates>
</Point>
</Placemark>
</Document>
</kml>
And here's the <description> without CDATA tags, so that special characters must use entity
references:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<Placemark>
<name>Entity references example</name>
<description>
<h1>Entity references are hard to type!</h1>
<p><font color="green">Text is
<i>more readable</i>
and <b>easier to write</b>
when you can avoid using entity references.</font></p>
</description>
<Point>
<coordinates>102.594411,14.998518</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Ground Overlays
Ground overlays enable you to "drape" an image onto the Earth's terrain. The <Icon> element contains
the link to the .jpg file with the overlay image. Here is the example ground overlay in the KML
Samples file, which shows Mount Etna erupting in 2001:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Folder>
<name>Ground Overlays</name>
<description>Examples of ground overlays</description>
<GroundOverlay>
<name>Large-scale overlay on terrain</name>
<description>Overlay shows Mount Etna erupting
on July 13th, 2001.</description>
<Icon>
<href>http://developers.google.com/kml/documentation/images/etna.jpg</href>
</Icon>
<LatLonBox>
<north>37.91904192681665</north>
<south>37.46543388598137</south>
<east>15.35832653742206</east>
<west>14.60128369746704</west>
<rotation>-0.1556640799496235</rotation>
</LatLonBox>
</GroundOverlay>
</Folder>
</kml>
Notice that the file begins with the same two lines as the first example: the XML header and KML
namespace declaration.
This example uses a Folder (titled "Ground Overlays") as a mechanism to group and label its contents.
Notice how the Folder appears in the Places panel when you load the KML Samples file into Google
Earth.
The positioning of a ground overlay is controlled by the <LatLonBox> tag. Bounding values are given
for the north and south latitudes, and east and west longitudes. In addition, rotation values are given for
images whose y-axis doesn't coincide with grid north. This example uses a JPEG image for the overlay.
Google Earth also supports BMP, GIF, TIFF, TGA, and PNG formats.
Paths
Many different types of paths can be created in Google Earth, and it is easy to be very creative with
your data. In KML, a path is created by a <LineString> element. Take a look at the "Absolute
Extruded" example in the Paths folder and you can see how the shape has been generated by the
following code:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>Paths</name>
<description>Examples of paths. Note that the tessellate tag is by default
set to 0. If you want to create tessellated lines, they must be authored
(or edited) directly in KML.</description>
<Style id="yellowLineGreenPoly">
<LineStyle>
<color>7f00ffff</color>
<width>4</width>
</LineStyle>
<PolyStyle>
<color>7f00ff00</color>
</PolyStyle>
</Style>
<Placemark>
<name>Absolute Extruded</name>
<description>Transparent green wall with yellow outlines</description>
<styleUrl>#yellowLineGreenPoly</styleUrl>
<LineString>
<extrude>1</extrude>
<tessellate>1</tessellate>
<altitudeMode>absolute</altitudeMode>
<coordinates> -112.2550785337791,36.07954952145647,2357
-112.2549277039738,36.08117083492122,2357
-112.2552505069063,36.08260761307279,2357
-112.2564540158376,36.08395660588506,2357
-112.2580238976449,36.08511401044813,2357
-112.2595218489022,36.08584355239394,2357
-112.2608216347552,36.08612634548589,2357
-112.262073428656,36.08626019085147,2357
-112.2633204928495,36.08621519860091,2357
-112.2644963846444,36.08627897945274,2357
-112.2656969554589,36.08649599090644,2357
</coordinates>
</LineString>
</Placemark>
</Document>
</kml>
Notice how it is really just one line drawn at altitude above the ground. The <tessellate> tag breaks the
line up into smaller chunks, and the <extrude> tag extends the line down to the ground.
Polygons
You can use Polygons to create simple buildings and other shapes. Check out the Polygons folder in the
KML Samples file for examples.
The Pentagon example is generated by drawing simple inner and outer shells and then extruding them
down to the ground. Here is the code :
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Placemark>
<name>The Pentagon</name>
<Polygon>
<extrude>1</extrude>
<altitudeMode>relativeToGround</altitudeMode>
<outerBoundaryIs>
<LinearRing>
<coordinates>
-77.05788457660967,38.87253259892824,100
-77.05465973756702,38.87291016281703,100
-77.05315536854791,38.87053267794386,100
-77.05552622493516,38.868757801256,100
-77.05844056290393,38.86996206506943,100
-77.05788457660967,38.87253259892824,100
</coordinates>
</LinearRing>
</outerBoundaryIs>
<innerBoundaryIs>
<LinearRing>
<coordinates>
-77.05668055019126,38.87154239798456,100
-77.05542625960818,38.87167890344077,100
-77.05485125901024,38.87076535397792,100
-77.05577677433152,38.87008686581446,100
-77.05691162017543,38.87054446963351,100
-77.05668055019126,38.87154239798456,100
</coordinates>
</LinearRing>
</innerBoundaryIs>
</Polygon>
</Placemark>
</kml>
hand" is a bit more advanced than using the Google Earth interface to create and modify features, but
with a small amount of practice, most users are comfortable editing KML files to add these effects.
-122.0850990714904,37.42251282407603,17
-122.0856769818632,37.42281815323651,17
-122.0860162273783,37.42244918858722,17
-122.0857260327004,37.42229239604253,17
-122.0857412771483,37.42227033155257,17
</coordinates>
</LinearRing>
</outerBoundaryIs>
</Polygon>
</Placemark>
</Document>
</kml>
Note that the <Style> element is a child of <Placemark> (not of the Geometry it affects).
</Style>
<StyleMap id="exampleStyleMap">
<Pair>
<key>normal</key>
<styleUrl>#normalPlacemark</styleUrl>
</Pair>
<Pair>
<key>highlight</key>
<styleUrl>#highlightPlacemark</styleUrl>
</Pair>
</StyleMap>
<Placemark>
<name>Roll over this icon</name>
<styleUrl>#exampleStyleMap</styleUrl>
<Point>
<coordinates>-122.0856545755255,37.42243077405461,0</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Screen Overlays
Screen overlays cannot be authored directly within Google Earth and are thus more difficult to create
than ground overlays. A comprehensive collection of samples is included in the Screen Overlays folder
in the KML Samples file.
As an example, enable the "Absolute Positioning: Top left" folder in the KML Samples file and you
will see a screen overlay at the top left of the view window. This was created with the following KML
code:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<ScreenOverlay>
<name>Absolute Positioning: Top left</name>
<Icon>
<href>http://developers.google.com/kml/documentation/images/top_left.jpg</href>
</Icon>
<overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
<screenXY x="0" y="1" xunits="fraction" yunits="fraction"/>
<rotationXY x="0" y="0" xunits="fraction" yunits="fraction"/>
<size x="0" y="0" xunits="fraction" yunits="fraction"/>
</ScreenOverlay>
</kml>
Positioning is controlled by mapping a point in the image specified by <overlayXY> to a point on the
screen specified by <screenXY>. In this case, the top-left corner of the image (0,1) has been made
coincident with the same point on the screen.
Check the other examples in the folder to see how it is possible to obtain other fixed positions, and to
create images that size dynamically with screen size. (Note that xunits and yunits can also be specified
as "pixels" for precision control.) For further detail, see the KML 2.2 Reference.
Network Links
A network link contains a <Link> element with an <href> (a hypertext reference) that loads a file. The
<href> can be a local file specification or an absolute URL. Despite the name, a <NetworkLink> does
not necessarily load files from the network.
The <href> in a link specifies the location of any of the following:
An image file used by icons in icon styles, ground overlays, and screen overlays
A model file used in the <Model> element
A KML or KMZ file loaded by a Network Link
The specified file can be either a local file or a file on a remote server. In their simplest form, network
links are a useful way to split one large KML file into smaller, more manageable files on the same
computer.
So far, all of our examples have required that the KML code be delivered to Google Earth from the
local machine. Network links give you the power to serve content from a remote location and are
commonly used to distribute data to large numbers of users. In this way, if the data needs to be
amended, it has to be changed only at the source location, and all users receive the updated data
automatically.
Here is an example of a KML file containing a Network Link that loads this Python script:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Folder>
<name>Network Links</name>
<visibility>0</visibility>
<open>0</open>
<description>Network link example 1</description>
<NetworkLink>
<name>Random Placemark</name>
<visibility>0</visibility>
<open>0</open>
<description>A simple server-side script that generates a new random
placemark on each call</description>
<refreshVisibility>0</refreshVisibility>
<flyToView>0</flyToView>
<Link>
<href>http:// yourserver.com/cgi-bin/randomPlacemark.py</href>
</Link>
</NetworkLink>
</Folder>
</kml>
If the request were made while the user was looking down on San Francisco, the coordinates might
look as follows:
GET /path/to/server/script/query?BBOX=-122.497790,37.730385,-122.380087,37.812331
HTTP/1.1
This feature can be used for some very creative applications, but to get you started, a simple example is
presented below.
And here is the KML for the Network Link that loads the Python script:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Folder>
<name>Network Links</name>
<visibility>0</visibility>
<open>0</open>
<description>Network link example 2</description>
<NetworkLink>
<name>View Centered Placemark</name>
<visibility>0</visibility>
<open>0</open>
<description>The view-based refresh allows the remote server to calculate
the center of your screen and return a placemark.</description>
<refreshVisibility>0</refreshVisibility>
<flyToView>0</flyToView>
<Link>
<href>http:// yourserver.com/cgi-bin/viewCenteredPlacemark.py</href>
<refreshInterval>2</refreshInterval>
<viewRefreshMode>onStop</viewRefreshMode>
<viewRefreshTime>1</viewRefreshTime>
</Link>
</NetworkLink>
</Folder>
</kml>
The principle illustrated in this example can be used for some very complex applications. For example,
if you have a database of geographic information, you can extract the coordinates of the viewer, make a
call to the database for the data specific to the view, and return it to Google Earth as KML.
What's Next?
Ready for more? Check out the Developer's Guide, which describes key KML features. Also, browse
the KML Reference for information on specific elements.
Last updated febbraio 24, 2012.