KML Reference

This section contains an alphabetical reference for all KML elements defined in KML Version 2.2. The class tree for KML elements is shown below. In this diagram, elements to the right on a particular branch in the tree are extensions of the elements to their left. For example, Placemark is a special kind of Feature. It contains all of the elements that belong to Feature, and it adds some elements that are specific to the Placemark element.

KML is an open standard officially named the OpenGIS® KML Encoding Standard (OGC KML). It is maintained by the Open Geospatial Consortium, Inc. (OGC). The complete specification for OGC KML can be found at http://www.opengeospatial.org/standards/kml/.

The complete XML schema for KML is located at http://schemas.opengis.net/kml/.

Note: Click an element name in this diagram to jump to its entry in the reference section.

Note that abstract elements (shown in italics and in dotted boxes in the diagram) are not actually used in KML files. They are a useful way for a single element to serve as the programmatic foundation for multiple similar (but different) derived elements. Understanding this object-oriented hierarchy is also a good way for you to learn KML, since you can easily see groupings of related elements.

All elements derived from Object can have an id assigned to them. This id is used by the KML update mechanism (see <Update>) for files loaded with a NetworkLink. It is also used by shared styles (see <Style>). The id is a standard XML ID.

Because KML is an XML grammar and file format, tag names are case-sensitive and must appear exactly as shown here. If you're familiar with XML, you will also be interested in the KML 2.2 Schema. When you are editing KML text files, you can load this Schema into any XML editor and validate your KML code with it.

Tip: Viewing KML for Google Earth Features

Here is a handy feature of Google Earth that makes it easy to view the KML file for any Feature. In Google Earth, you can right-click a Feature in the Places panel and copy it. To view the corresponding KML for the copied object, open your favorite text editor and paste the selection into it.

Compatibility

KML versions have a double numbering system: majorVersion.minorVersion. All versions with the same majorVersion are compatible. For this reason, if you change the namespace to "2.2" (that is, xmlns="http://www.opengis.net/kml/2.2"), all KML 2.1 files validate in the KML 2.2 schema.

About This Reference

Each reference entry includes a Syntax section that lists the elements contained in the main element. This Syntax section is an informal listing and uses simple shorthand to summarize the elements. This section also contains the following:

• default values for each element (or ellipses if it is a complex element or if there is no default value)
• the type of the value (see KML Fields)

The Syntax section can be copied and used as a template for any non-abstract element in a KML file.

KML Fields

KML uses common XML types such as boolean, string, double, float, and int. In addition, it defines a number of field element types. The following table lists some of the most commonly used types defined in KML and links to sample elements that use them:

Field Type	Value	Example Use
altitudeModeEnum	clampToGround, relativeToGround, absolute	See <LookAt> and <Region>
angle90	a value ≥−90 and ≤90	See <latitude> in <Model>
anglepos90	a value ≥0 and ≤90	See <tilt> in <LookAt>
angle180	a value ≥−180 and ≤180	See <longitude> in <Model>
angle360	a value ≥−360 and ≤360	See <heading>, <tilt>, and <roll> in <Orientation>
color	hexBinary value: aabbggrr	See any element that extends <ColorStyle>
colorModeEnum	normal, random	See any element that extends <ColorStyle>
dateTime	dateTime, date, gYearMonth, gYear	See <TimeSpan> and <TimeStamp>
displayModeEnum	default, hide	See <BalloonStyle>
gridOrigin	lowerLeft, upperLeft	See <PhotoOverlay>
refreshModeEnum	onChange, onInterval, onExpire	See <Link>
shapeEnum	rectangle, cylinder, sphere	See <PhotoOverlay>
styleStateEnum	normal, highlight	See <StyleMap>
unitsEnum	fraction, pixels, insetPixels	See <hotSpot> in <IconStyle>, <ScreenOverlay>
vec2	x=double xunits=kml:unitsEnum y=double yunits=kml:unitsEnum	See <hotSpot> in <IconStyle>, <ScreenOverlay>
viewRefreshEnum	never, onRequest, onStop, onRegion	See <Link>

<AbstractView> new in 2.2

Syntax

<!-- abstract element; do not create -->
<!-- AbstractView -->                   <!-- Camera, LookAt -->                
  <!-- extends Object -->
<-- /AbstractView -->

Description

This is an abstract element and cannot be used directly in a KML file. This element is extended by the <Camera> and <LookAt> elements.

Extends

<Object>

Extended By

• <Camera>
• <LookAt>

<BalloonStyle>

Syntax

<BalloonStyle id="ID">
  <!-- specific to BalloonStyle -->
  <bgColor>ffffffff</bgColor>            <!-- kml:color -->
  <textColor>ff000000</textColor>        <!-- kml:color --> 
  <text>...</text>                       <!-- string -->
  <displayMode>default</displayMode>     <!-- kml:displayModeEnum -->
</BalloonStyle>

Description

Specifies how the description balloon for placemarks is drawn. The <bgColor>, if specified, is used as the background color of the balloon. See <Feature> for a diagram illustrating how the default description balloon appears in Google Earth.

Elements Specific to BalloonStyle

<bgColor>

Background color of the balloon (optional). Color and opacity (alpha) values are expressed in hexadecimal notation. The range of values for any one color is 0 to 255 (00 to ff). The order of expression is aabbggrr, where aa=alpha (00 to ff); bb=blue (00 to ff); gg=green (00 to ff); rr=red (00 to ff). For alpha, 00 is fully transparent and ff is fully opaque. For example, if you want to apply a blue color with 50 percent opacity to an overlay, you would specify the following: <bgColor>7fff0000</bgColor>, where alpha=0x7f, blue=0xff, green=0x00, and red=0x00. The default is opaque white (ffffffff).

Note: The use of the <color> element within <BalloonStyle> has been deprecated. Use <bgColor> instead.

<textColor>

Foreground color for text. The default is black (ff000000).

<text>

Text displayed in the balloon. If no text is specified, Google Earth draws the default balloon (with the Feature <name> in boldface, the Feature <description>, links for driving directions, a white background, and a tail that is attached to the point coordinates of the Feature, if specified).

You can add entities to the <text> tag using the following format to refer to a child element of Feature: $[name], $[description], $[address], $[id], $[Snippet]. Google Earth looks in the current Feature for the corresponding string entity and substitutes that information in the balloon. To include To here - From here driving directions in the balloon, use the $[geDirections] tag. To prevent the driving directions links from appearing in a balloon, include the <text> element with some content, or with $[description] to substitute the basic Feature <description>.

For example, in the following KML excerpt, $[name] and $[description] fields will be replaced by the <name> and <description> fields found in the Feature elements that use this BalloonStyle:

<text>This is $[name], whose description is:<br/>$[description]</text>

<displayMode>

If <displayMode> is default, Google Earth uses the information supplied in <text> to create a balloon . If <displayMode> is hide, Google Earth does not display the balloon. In Google Earth, clicking the List View icon for a Placemark whose balloon's <displayMode> is hide causes Google Earth to fly to the Placemark.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>BalloonStyle.kml</name>
  <open>1</open>
  <Style id="exampleBalloonStyle">
    <BalloonStyle>
      <!-- a background color for the balloon -->
      <bgColor>ffffffbb</bgColor>
      <!-- styling of the balloon text -->
      <text><![CDATA[
      <b><font color="#CC0000" size="+3">$[name]</font></b>
      <br/><br/>
      <font face="Courier">$[description]</font>
      <br/><br/>
      Extra text that will appear in the description balloon
      <br/><br/>
      <!-- insert the to/from hyperlinks -->
      $[geDirections]
      ]]></text>
    </BalloonStyle>
  </Style>
  <Placemark>
    <name>BalloonStyle</name>
    <description>An example of BalloonStyle</description>
    <styleUrl>#exampleBalloonStyle</styleUrl>
    <Point>
      <coordinates>-122.370533,37.823842,0</coordinates>
    </Point>
  </Placemark>
</Document>
</kml>

Extends

• <ColorStyle>

Contained By

• <Style>

Back to top

<Camera> new in 2.2

Syntax

<Camera id="ID">
   <longitude>0</longitude>          <!-- kml:angle180 --> 
   <latitude>0</latitude>            <!-- kml:angle90 -->
   <altitude>0</altitude>            <!-- double -->
   <heading>0</heading>              <!-- kml:angle360 -->
   <tilt>0</tilt>                    <!-- kml:anglepos180 -->
   <roll>0</roll>                    <!-- kml:angle180 -->
   <altitudeMode>clampToGround</altitudeMode>              
         <!-- kml:altitudeModeEnum: relativeToGround, clampToGround, or absolute -->
 </Camera> 

Description

Defines the virtual camera that views the scene. This element defines the position of the camera relative to the Earth's surface as well as the viewing direction of the camera. The camera position is defined by <longitude>, <latitude>, <altitude>, and <altitudeMode>. The viewing direction of the camera is defined by <heading>, <tilt>, and <roll>. <Camera> can be a child element of any <Feature> or of <NetworkLinkControl>. A parent element cannot contain both a <Camera> and a <LookAt> at the same time.

<Camera> provides full six-degrees-of-freedom control over the view, so you can position the Camera in space and then rotate it around the X, Y, and Z axes. Most importantly, you can tilt the camera view so that you're looking above the horizon into the sky.

Defining a View

Within a <Feature> or <NetworkLinkControl>, use either a <Camera> or a <LookAt> object (but not both in the same object). The <Camera> object defines the viewpoint in terms of the viewer's position and orientation. The <Camera> object allows you to specify a view that is not on the Earth's surface. The <LookAt> object defines the viewpoint in terms of what is being viewed. The <LookAt> object is more limited in scope than <Camera> and generally requires that the view direction intersect the Earth's surface.

The following diagram shows the X, Y, and Z axes, which are attached to the virtual camera.

• The X axis points toward the right of the camera and is called the right vector.
• The Y axis defines the "up" direction relative to the screen and is called the up vector.
• The Z axis points from the center of the screen toward the eye point. The camera looks down the −Z axis, which is called the view vector.

Order of Transformations

The order of rotation is important. By default, the camera is looking straight down the −Z axis toward the Earth. Before rotations are performed, the camera is translated along the Z axis to <altitude>. The order of transformations is as follows:

1. <altitude> - translate along the Z axis to <altitude>
2. <heading> - rotate around the Z axis.
3. <tilt> - rotate around the X axis.
4. <roll> - rotate around the Z axis (again).

Note that each time a rotation is applied, two of the camera axes change their orientation.

Elements Specific to Camera

<longitude>

Longitude of the virtual camera (eye point). Angular distance in degrees, relative to the Prime Meridian. Values west of the Meridian range from −180 to 0 degrees. Values east of the Meridian range from 0 to 180 degrees.

<latitude>

Latitude of the virtual camera. Degrees north or south of the Equator (0 degrees). Values range from −90 degrees to 90 degrees.

<altitude>

Distance of the camera from the earth's surface, in meters. See <altitudeMode> for how this value is interpreted.

<heading>

Direction (azimuth) of the camera, in degrees. Default=0 (true North). (See diagram.) Values range from 0 to 360 degrees.

<tilt>

Rotation, in degrees, of the camera around the X axis. A value of 0 indicates that the view is aimed straight down toward the earth (the most common case). A value for 90 for <tilt> indicates that the view is aimed toward the horizon. Values greater than 90 indicate that the view is pointed up into the sky. Values for <tilt> are clamped at +180 degrees.

<roll>

Rotation, in degrees, of the camera around the Z axis. Values range from −180 to +180 degrees.

<altitudeMode>

Specifies how the <altitude> specified for the Camera is interpreted. Possible values are as follows:

• relativeToGround - (default) Interprets the <altitude> as a value in meters above the ground.
• clampToGround - Indicates to ignore the <altitude> specification and place the Camera position on the ground.
• absolute - Interprets the <altitude> as a value in meters above sea level.

Extends

• <AbstractView>

Contained By

• Any element derived from <Feature>
• <NetworkLinkControl>

Back to top

<ColorStyle>

Syntax

<!-- abstract element; do not create -->
<!-- ColorStyle id="ID" -->          <!-- IconStyle,LabelStyle,LineStyle,PolyStyle -->
  <color>ffffffff</color>            <!-- kml:color -->
  <colorMode>normal</colorMode>      <!-- kml:colorModeEnum: normal or random -->
<!-- /ColorStyle -->

Description

This is an abstract element and cannot be used directly in a KML file. It provides elements for specifying the color and color mode of extended style types.

Elements Specific to ColorStyle

<color>

Color and opacity (alpha) values are expressed in hexadecimal notation. The range of values for any one color is 0 to 255 (00 to ff). For alpha, 00 is fully transparent and ff is fully opaque. The order of expression is aabbggrr, where aa=alpha (00 to ff); bb=blue (00 to ff); gg=green (00 to ff); rr=red (00 to ff). For example, if you want to apply a blue color with 50 percent opacity to an overlay, you would specify the following: <color>7fff0000</color>, where alpha=0x7f, blue=0xff, green=0x00, and red=0x00.

<colorMode>

Values for <colorMode> are normal (no effect) and random. A value of random applies a random linear scale to the base <color> as follows.

• To achieve a truly random selection of colors, specify a base <color> of white (00ffffff).
• If you specify a single color component (for example, a value of ff0000ff for red), random color values for that one component (red) will be selected. In this case, the values would range from 00 (black) to ff (full red).
• If you specify values for two or for all three color components, a random linear scale is applied to each color component, with results ranging from black to the maximum values specified for each component.
• The opacity of a color comes from the alpha component of <color> and is never randomized.

Extends

• <Object>

Extended By

• <IconStyle>
• <LabelStyle>
• <LineStyle>
• <PolyStyle>

Back to top

<Container>

Syntax

<!-- abstract element; do not create -->
<!-- Container id="ID" -->              <!-- Document,Folder -->                 
  <!-- inherited from Feature element -->
  <name>...</name>                      <!-- string -->
  <visibility>1</visibility>            <!-- boolean -->
  <open>0</open>                        <!-- boolean -->
  <address>...</address>                <!-- string -->
  <AddressDetails xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">...
      </AddressDetails>                 <!-- string -->
  <phoneNumber>...</phoneNumber>        <!-- string -->
  <Snippet maxLines="2">...</Snippet>   <!-- string -->
  <description>...</description>        <!-- string -->
  <AbstractView>...</AbstractView>      <!-- LookAt or Camera -->
  <TimePrimitive>...</TimePrimitive>
  <styleUrl>...</styleUrl>              <!-- anyURI -->
  <StyleSelector>...</StyleSelector>
  <Region>...</Region>
  <Metadata>...</Metadata>
  <atom:author>...<atom:author>   <!-- xmlns:atom="http://www.w3.org/2005/Atom" -->
  <atom:link>...</atom:link>

  <!-- specific to Container --> 
  <!-- 0 or more Features --> 
<!-- /Container -->

Description

This is an abstract element and cannot be used directly in a KML file. A Container element holds one or more Features and allows the creation of nested hierarchies.

Extends

• <Feature>

Extended By

• <Document>
• <Folder>

Back to top

<Document>

Syntax

<Document id="ID">
  <!-- inherited from Feature element -->
  <name>...</name>                      <!-- string -->
  <visibility>1</visibility>            <!-- boolean -->
  <open>0</open>                        <!-- boolean -->
  <atom:author>...<atom:author>         <!-- xmlns:atom -->
  <atom:link>...</atom:link>            <!-- xmlns:atom -->
  <address>...</address>                <!-- string -->
  <xal:AddressDetails>...</xal:AddressDetails>  <!-- xmlns:xal -->
  <phoneNumber>...</phoneNumber>        <!-- string -->
  <Snippet maxLines="2">...</Snippet>   <!-- string -->
  <description>...</description>        <!-- string -->
  <AbstractView>...</AbstractView>      <!-- Camera or LookAt -->
  <TimePrimitive>...</TimePrimitive>
  <styleUrl>...</styleUrl>              <!-- anyURI -->
  <StyleSelector>...</StyleSelector>
  <Region>...</Region>
  <Metadata>...</Metadata>              <!-- deprecated in KML 2.2 -->
  <ExtendedData>...</ExtendedData>      <!-- new in KML 2.2 -->

  <!-- specific to Document -->
  <!-- 0 or more Schema elements -->
  <!-- 0 or more Feature elements -->
</Document>

Description

A Document is a container for features and styles. This element is required if your KML file uses shared styles. It is recommended that you use shared styles, which require the following steps:

1. Define all Styles in a Document. Assign a unique ID to each Style.
2. Within a given Feature or StyleMap, reference the Style's ID using a <styleUrl> element.

Note that shared styles are not inherited by the Features in the Document.

Each Feature must explicitly reference the styles it uses in a <styleUrl> element. For a Style that applies to a Document (such as ListStyle), the Document itself must explicitly reference the <styleUrl>. For example:

<Document>
  <Style id="myPrettyDocument">
   <ListStyle> ... </ListStyle>

  </Style>
  <styleUrl#myPrettyDocument">
  ...
</Document> 

Do not put shared styles within a Folder.

The following example illustrates use of a shared style.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>Document.kml</name>
  <open>1</open>
  <Style id="exampleStyleDocument">
    <LabelStyle>
      <color>ff0000cc</color>
    </LabelStyle>
  </Style>
  <Placemark>
    <name>Document Feature 1</name>
    <styleUrl>#exampleStyleDocument</styleUrl>
    <Point>
      <coordinates>-122.371,37.816,0</coordinates>
    </Point>
  </Placemark>
  <Placemark>
    <name>Document Feature 2</name>
    <styleUrl>#exampleStyleDocument</styleUrl>
    <Point>
      <coordinates>-122.370,37.817,0</coordinates>
    </Point>
  </Placemark>
</Document>
</kml>

Extends

• <Container>

Contains

• 0 or more elements derived from <Feature>
• 0 or more elements derived from <StyleSelector>
• 0 or more elements derived from <Schema>

Back to top

<ExtendedData> new in 2.2

Syntax

<ExtendedData>                       
  <Data name="string">
    <displayName>...</displayName>    <!-- string -->
    <value>...</value>                <!-- string -->
  </Data>
  <SchemaData schemaUrl="anyURI">
    <SimpleData name=""> ... </SimpleData>   <!-- string -->
  </SchemaData>
  <namespace_prefix:other>...</namespace_prefix:other>
</ExtendedData>

Description

The ExtendedData element offers three techniques for adding custom data to a KML Feature (NetworkLink, Placemark, GroundOverlay, PhotoOverlay, ScreenOverlay, Document, Folder). These techniques are

• Adding untyped data/value pairs using the <Data> element (basic)
• Declaring new typed fields using the <Schema> element and then instancing them using the <SchemaData> element (advanced)
• Referring to XML elements defined in other namespaces by referencing the external namespace within the KML file (basic)

These techniques can be combined within a single KML file or Feature for different pieces of data.

For more information, see Adding Custom Data in "Topics in KML."

Elements Specific to ExtendedData

<Data name ="string">

Creates an untyped name/value pair. The name can have two versions: name and displayName. The name attribute is used to identify the data pair within the KML file. The displayName element is used when a properly formatted name, with spaces and HTML formatting, is displayed in Google Earth. In the <text> element of <BalloonStyle>, the notation $[name:displayName] is replaced with <displayName>. If you substitute the value of the name attribute of the <Data> element in this format (for example, $[holeYardage], the attribute value is replaced with <value>. By default, the Placemark's balloon displays the name/value pairs associated with it.

<displayName>

An optional formatted version of name, to be used for display purposes.

<value>

Value of the data pair.

<Placemark>
  <name>Club house</name>
  <ExtendedData>
    <Data name="holeNumber">
      <value>1</value>
    </Data>
    <Data name="holeYardage">
      <value>234</value>
    </Data>
    <Data name="holePar">
      <value>4</value>
    </Data>
  </ExtendedData>
</Placemark>

<SchemaData schemaUrl="anyURI">

This element is used in conjunction with <Schema> to add typed custom data to a KML Feature. The Schema element (identified by the schemaUrl attribute) declares the custom data type. The actual data objects ("instances" of the custom data) are defined using the SchemaData element.

The <schemaURL> can be a full URL, a reference to a Schema ID defined in an external KML file, or a reference to a Schema ID defined in the same KML file. All of the following specifications are acceptable:

schemaUrl="http://host.com/PlacesIHaveLived.kml#my-schema-id"

schemaUrl="AnotherFile.kml#my-schema-id"

schemaUrl="#schema-id"   <!-- same file -->

The Schema element is always a child of Document. The ExtendedData element is a child of the Feature that contains the custom data.

<SimpleData name="string">

This element assigns a value to the custom data field identified by the name attribute. The type and name of this custom data field are declared in the <Schema> element.

Here is an example of defining two custom data elements:

<Placemark>
  <name>Easy trail</name>
  <ExtendedData>
    <SchemaData schemaUrl="#TrailHeadTypeId">
      <SimpleData name="TrailHeadName">Pi in the sky</SimpleData>
      <SimpleData name="TrailLength">3.14159</SimpleData>
      <SimpleData name="ElevationGain">10</SimpleData>
    </SchemaData>
    </ExtendedData>
    <Point>
      <coordinates>-122.000,37.002</coordinates>
    </Point>
</Placemark>
<Placemark>
  <name>Difficult trail</name>
  <ExtendedData>
    <SchemaData schemaUrl="#TrailHeadTypeId">
      <SimpleData name="TrailHeadName">Mount Everest</SimpleData>
      <SimpleData name="TrailLength">347.45</SimpleData>
      <SimpleData name="ElevationGain">10000</SimpleData>
    </SchemaData>
  </ExtendedData>
  <Point>
    <coordinates>-122.000,37.002</coordinates>
  </Point>
</Placemark>

<namespace_prefix:other>

This element allows you to add untyped custom data. Be sure to reference the namespace prefix in the <kml> element of your file or as an attribute of the <ExtendedData> element and to prefix the name of each data element with the namespace prefix. Custom data added in this manner is preserved in the KML file but is not used by Google Earth in any way. It is always saved along with the file.

The following example shows using the "camp" namespace prefix:

<ExtendedData xmlns:prefix="camp">
  <camp:number>14</camp:number>
  <camp:parkingSpaces>2</camp:parkingSpaces>
  <camp:tentSites>4</camp:tentSites>
</ExtendedData>

Contained By

• Any element derived from <Feature>

See Also

• Schema

<Feature>

Syntax

<!-- abstract element; do not create -->
<!-- Feature id="ID" -->                <!-- Document,Folder,
                                             NetworkLink,Placemark,
                                             GroundOverlay,PhotoOverlay,ScreenOverlay -->
  <name>...</name>                      <!-- string -->
  <visibility>1</visibility>            <!-- boolean -->
  <open>0</open>                        <!-- boolean -->
  <atom:author>...<atom:author>         <!-- xmlns:atom -->
  <atom:link>...</atom:link>            <!-- xmlns:atom -->
  <address>...</address>                <!-- string -->
  <xal:AddressDetails>...</xal:AddressDetails>  <!-- xmlns:xal -->
  <phoneNumber>...</phoneNumber>        <!-- string -->
  <Snippet maxLines="2">...</Snippet>   <!-- string -->
  <description>...</description>        <!-- string -->
  <AbstractView>...</AbstractView>      <!-- Camera or LookAt -->
  <TimePrimitive>...</TimePrimitive>    <!-- TimeStamp or TimeSpan -->
  <styleUrl>...</styleUrl>              <!-- anyURI -->
  <StyleSelector>...</StyleSelector>
  <Region>...</Region>
  <Metadata>...</Metadata>              <!-- deprecated in KML 2.2 -->
  <ExtendedData>...</ExtendedData>      <!-- new in KML 2.2 -->
<-- /Feature -->

Description

This is an abstract element and cannot be used directly in a KML file. The following diagram shows how some of a Feature's elements appear in Google Earth.

Elements Specific to Feature

<name>

User-defined text displayed in the 3D viewer as the label for the object (for example, for a Placemark, Folder, or NetworkLink).

<visibility>

Boolean value. Specifies whether the feature is drawn in the 3D viewer when it is initially loaded. In order for a feature to be visible, the <visibility> tag of all its ancestors must also be set to 1. In the Google Earth List View, each Feature has a checkbox that allows the user to control visibility of the Feature.

<open>

Boolean value. Specifies whether a Document or Folder appears closed or open when first loaded into the Places panel. 0=collapsed (the default), 1=expanded. See also <ListStyle>. This element applies only to Document, Folder, and NetworkLink.

<atom:author>

KML 2.2 supports new elements for including data about the author and related website in your KML file. This information is displayed in geo search results, both in Earth browsers such as Google Earth, and in other applications such as Google Maps. The ascription elements used in KML are as follows:

• atom:author element - parent element for atom:name
• atom:name element - the name of the author
• atom:link element - contains the href attribute
• href attribute - URL of the web page containing the KML/KMZ file

These elements are defined in the Atom Syndication Format. The complete specification is found at http://atompub.org. Be sure to include the namespace for this element in any KML file that uses it: xmlns:atom="http://www.w3.org/2005/Atom" (see the sample that follows).

The <atom:author> element is the parent element for <atom:name>, which specifies the author of the KML feature.

<atom:link href="..." >

Specifies the URL of the website containing this KML or KMZ file. Be sure to include the namespace for this element in any KML file that uses it: xmlns:atom="http://www.w3.org/2005/Atom" (see the sample that follows).

<address>

A string value representing an unstructured address written as a standard street, city, state address, and/or as a postal code. You can use the <address> tag to specify the location of a point instead of using latitude and longitude coordinates. (However, if a <Point> is provided, it takes precedence over the <address>.) To find out which locales are supported for this tag in Google Earth, go to the Google Maps Help.

<xal:AddressDetails>

A structured address, formatted as xAL, or eXtensible Address Language, an international standard for address formatting. <xal:AddressDetails> is used by KML for geocoding in Google Maps only. For details, see the Google Maps API documentation. Currently, Google Earth does not use this element; use <address> instead. Be sure to include the namespace for this element in any KML file that uses it: xmlns:xal="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"

<phoneNumber>

A string value representing a telephone number. This element is used by Google Maps Mobile only. The industry standard for Java-enabled cellular phones is RFC2806.
For more information, see http://www.ietf.org/rfc /rfc2806.txt. 

<Snippet maxLines="2" >

A short description of the feature. In Google Earth, this description is displayed in the Places panel under the name of the feature. If a Snippet is not supplied, the first two lines of the <description> are used. In Google Earth, if a Placemark contains both a description and a Snippet, the <Snippet> appears beneath the Placemark in the Places panel, and the <description> appears in the Placemark's description balloon. This tag does not support HTML markup. <Snippet> has a maxLines attribute, an integer that specifies the maximum number of lines to display.

<description>

User-supplied text that appears in the description balloon.

The <description> element supports plain text as well as a subset of HTML formatting elements, including tables (see KML example below). It does not support other web-based technology, such as dynamic page markup (PHP, JSP, ASP), scripting languages (VBScript, Javascript), nor application languages (Java, Python). In Google Earth release 4.2, video is supported. (See Example below.)

If your description contains no HTML markup, Google Earth attempts to format it, replacing newlines with <br> and wrapping URLs with anchor tags. A valid URL string for the World Wide Web is automatically converted to a hyperlink to that URL (e.g., http://www.google.com). Consequently, you do not need to surround a URL with the <a href="http://.."></a> tags in order to achieve a simple link.

When using HTML to create a hyperlink around a specific word, or when including images in the HTML, you must use HTML entity references or the CDATA element to escape angle brackets, apostrophes, and other special characters. The CDATA element tells the XML parser to ignore special characters used within the brackets. This element takes the form of:

<![CDATA[
  special characters here
]]> 

If you prefer not to use the CDATA element, you can use entity references to replace all the special characters.

<description>
  <![CDATA[
This is an image 
<img src="icon.jpg"> 
and we have a link http://www.google.com.
  ]]>
</description>

Other Behavior Specified Through Use of the <a> Element

KML 2.2 supports the use of two attributes within the <a> element: href and type.

The anchor element <a> contains an href attribute that specifies a URL.

If the href is a KML file and has a .kml or .kmz file extension, Google Earth loads that file directly when the user clicks it. If the URL ends with an extension not known to Google Earth (for example, .html), the URL is sent to the browser.

The href can be a fragment URL (that is, a URL with a # sign followed by a KML identifier). When the user clicks a link that includes a fragment URL, by default the browser flies to the Feature whose ID matches the fragment. If the Feature has a LookAt or Camera element, the Feature is viewed from the specified viewpoint.

The behavior can be further specified by appending one of the following three strings to the fragment URL:

• ;flyto (default) - fly to the Feature
• ;balloon - open the Feature's balloon but do not fly to the Feature
• ;balloonFlyto - open the Feature's balloon and fly to the Feature

For example, the following code indicates to open the file CraftsFairs.kml, fly to the Placemark whose ID is "Albuquerque," and open its balloon:

<description>
  <![CDATA[ 
    <a href="http://myServer.com/CraftsFairs.kml#Albuquerque;balloonFlyto">
      One of the Best Art Shows in the West</a>
  ]]>
</description> 

The type attribute is used within the <a> element when the href does not end in .kml or .kmz, but the reference needs to be interpreted in the context of KML. Specify the following:

type="application/vnd.google-earth.kml+xml" 

For example, the following URL uses the type attribute to notify Google Earth that it should attempt to load the file, even though the file extension is .php:

<a href="myserver.com/cgi-bin/generate-kml.php#placemark123"
   type="application/vnd.google-earth.kml+xml">

<AbstractView>

Defines a viewpoint associated with any element derived from Feature. See <Camera> and <LookAt>.

<TimePrimitive>

Associates this Feature with a period of time (<TimeSpan>) or a point in time (<TimeStamp>).

<styleUrl>

URL of a <Style> or <StyleMap> defined in a Document. If the style is in the same file, use a # reference. If the style is defined in an external file, use a full URL along with # referencing. Examples are

<styleUrl>#myIconStyleID</styleUrl>

<styleUrl>http://someserver.com/somestylefile.xml#restaurant</styleUrl>

<styleUrl>eateries.kml#my-lunch-spot</styleUrl>

<StyleSelector>

One or more Styles and StyleMaps can be defined to customize the appearance of any element derived from Feature or of the Geometry in a Placemark. (See <BalloonStyle>, <ListStyle>, <StyleSelector>, and the styles derived from <ColorStyle>.) A style defined within a Feature is called an "inline style" and applies only to the Feature that contains it. A style defined as the child of a <Document> is called a "shared style." A shared style must have an id defined for it. This id is referenced by one or more Features within the <Document>. In cases where a style element is defined both in a shared style and in an inline style for a Feature—that is, a Folder, GroundOverlay, NetworkLink, Placemark, or ScreenOverlay—the value for the Feature's inline style takes precedence over the value for the shared style.

<Region>

Features and geometry associated with a Region are drawn only when the Region is active. See <Region>.

<Metadata> (deprecated in KML 2.2; use <ExtendedData> instead)

<ExtendedData>

Allows you to add custom data to a KML file. This data can be (1) data that references an external XML schema, (2) untyped data/value pairs, or (3) typed data. A given KML Feature can contain a combination of these types of custom data.

Sample Use of HTML Elements within a Description

This example illustrates the complete set of HTML elements supported by the <description> element.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Placemark>
  <name>Feature.kml</name>
  <Snippet maxLines="4">
    The snippet is a way of
    providing an alternative
    description that will be
    shown in the List view.
  </Snippet> 
  <description>
    <![CDATA[
      Styles: <i>Italics</i>, <b>Bold</b>, <u>Underlined</u>, 
      <s>Strike Out</s>, subscript<sub>subscript</sub>,
      superscript<sup>superscript</sup>,  
      <big>Big</big>, <small>Small</small>, <tt>Typewriter</tt>,
      <em>Emphasized</em>, <strong>Strong</strong>, <code>Code</code>
      <hr />
      Fonts: 
      <font color="red">red by name</font>, 
      <font color="#408010">leaf green by hexadecimal RGB</font>, 
      <font size=1>size 1</font>, <font size=2>size 2</font>,
      <font size=3>size 3</font>, <font size=4>size 4</font>,
      <font size=5>size 5</font>, <font size=6>size 6</font>, 
      <font size=7>size 7</font>,
      <font face=times>Times</font>, 
      <font face=verdana>Verdana</font>, 
      <font face=arial>Arial</font>
      <br/>
      <hr />
      Links:
      <a href="http://doc.trolltech.com/3.3/qstylesheet.html">
      QT Rich Text Rendering
      </a>
      <br />
      <hr />
      Alignment:
      <br />
      <p align=left>left</p><p align=center>center</p>
      <p align=right>right</p>
      <hr />
      Ordered Lists:
      <br />
      <ol><li>First</li><li>Second</li><li>Third</li></ol>
      <ol type="a"><li>First</li><li>Second</li><li>Third</li></ol>
      <ol type="A"><li>First</li><li>Second</li><li>Third</li></ol>
      <hr />
      Unordered Lists:
      <br />
      <ul><li>A</li><li>B</li><li>C</li></ul>
      <ul type="circle"><li>A</li><li>B</li><li>C</li></ul>
      <ul type="square"><li>A</li><li>B</li><li>C</li></ul>
      <hr />
      Definitions:
      <br />
      <dl>
      <dt>Scrumpy</dt>
      <dd>Hard English cider from the west country</dd>
      <dt>Pentanque</dt>
      <dd>A form of boules where the goal is to throw metal ball as
      close as possible to a jack</dd>
      </dl>
      <hr />
      Block Quote:
      <br />
      <blockquote>
      We shall not cease from exploration<br />
      And the end of all our exploring<br />
      Will be to arrive where we started<br />
      And know the place for the first time
      </blockquote>
      <br />
      <hr />
      Centered:
      <br />
      <center>See, I have a Rhyme assisting<br />
      my feeble brain,<br />
      its tasks oft-times resisting!</center>
      <hr />
      Headings:
      <br />
      <h1>Header 1</h1>
      <h2>Header 2</h2>
      <h3>Header 3</h3>
      <h3>Header 4</h4>
      <h3>Header 5</h5>
      <hr />
      Images:
      <br />
      <img src="http://earth.google.com/images/googleearth.gif" />
      <br />
      <i>Scaled image</i>
      <br />
      <img src="http://earth.google.com/images/googleearth.gif"
      width="100" />
      <br />
      <hr />
      Tables:
      <table border="1" padding="3" width="300">
      <tr><td>1</td><td>2</td><td>3</td><td>4</td><td>5</td></tr>
      <tr><td>a</td><td>b</td><td>c</td><td>d</td><td>e</td></tr>
      </table>
    ]]>
  </description>
  <Point>
    <coordinates>-122.378927,37.826793,0</coordinates>
  </Point>
</Placemark>
</kml>

Sample Use of Ascription Elements

This example shows use of the <atom:author>, <atom:name> and <atom:link> elements from the Atom namespace. Note that you need to reference this namespace within the <kml> element.

<kml xmlns="http://www.opengis.net/kml/2.2"       
     xmlns:atom="http://www.w3.org/2005/Atom">   
  <Document>         
    <atom:author>             
      <atom:name>J. K. Rowling</atom:name>         
    </atom:author>         
    <atom:link href="http://www.harrypotter.com" />
    <Placemark>             
      <name>Hogwarts</name>             
      <Point>                 
        <coordinates>1,1</coordinates>             
      </Point>         
    </Placemark>         
    <Placemark>       
      <name>Little Hangleton</name>       
      <Point>         
        <coordinates>1,2</coordinates>       
      </Point>         
    </Placemark>     
  </Document>  
</kml>

This example shows how to embed a Flash video inside the Balloon.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>      
    <name>Video Example</name>
    <Style id="sn_blue-dot_copy3">
      <IconStyle>
        <Icon>
          
          <href>http://www.google.com/intl/en_us/mapfiles/ms/icons/blue-dot.png</href>
        </Icon>
      </IconStyle>
    </Style>
    <Placemark>
      <name>Placemark</name>
      <description>
        <![CDATA[<div style="font-size:larger">
          <div>
            <div style="width: 212px; font-size: 12px;">
              <b>The Spaghetti Film</b>
            </div>
            <div style="font-size: 11px;">
              <a target="_blank" href="http://www.youtube.com/?v=FICUvrVlyXc">
                http://www.youtube.com/?v=FICUvrVlyXc</a><br>
            </div><br>
            <div style="margin-left: auto; margin-right:auto;">
              <object height="175" width="212">
                <param value="http://www.youtube.com/v/FICUvrVlyXc" name="movie">
                <param value="transparent" name="wmode">
                <embed wmode="transparent" type="application/x-shockwave-flash"
                   src="http://www.youtube.com/v/FICUvrVlyXc" height="175"
                   width="212">
               </object>
             </div>
           </div>
          </div>
          <div style="font-size: smaller; margin-top: 1em;">Saved from 
            <a href="http://maps.google.com/ig/add?synd=mpl&pid=mpl&moduleurl=
                http:%2F%2Fwww.google.com%2Fig%2Fmodules%2Fmapplets-youtube.xml&hl=en&gl=us">
                YouTubeVideos</a>
          </div>
         ]]>
      </description>
      <styleUrl>#sn_blue-dot_copy3</styleUrl>
      <Point>
        <coordinates>-93.47875999999999,45.083248,0</coordinates>
      </Point>
    </Placemark>
</Document>
</kml>

Extends

• <Object>

Extended By

• <Container>
• <Overlay>
• <Placemark>

<Folder>

Syntax

<Folder id="ID">
  <!-- inherited from Feature element -->
  <name>...</name>                      <!-- string -->
  <visibility>1</visibility>            <!-- boolean -->
  <open>0</open>                        <!-- boolean -->
  <atom:author>...<atom:author>         <!-- xmlns:atom -->
  <atom:link>...</atom:link>            <!-- xmlns:atom -->
  <address>...</address>                <!-- string -->
  <xal:AddressDetails>...</xal:AddressDetails>  <!-- xmlns:xal -->
  <phoneNumber>...</phoneNumber>        <!-- string -->
  <Snippet maxLines="2">...</Snippet>   <!-- string -->
  <description>...</description>        <!-- string -->
  <AbstractView>...</AbstractView>      <!-- Camera or LookAt -->
  <TimePrimitive>...</TimePrimitive>
  <styleUrl>...</styleUrl>              <!-- anyURI -->
  <StyleSelector>...</StyleSelector>
  <Region>...</Region>
  <Metadata>...</Metadata>              <!-- deprecated in KML 2.2 -->
  <ExtendedData>...</ExtendedData>      <!-- new in KML 2.2 -->

  <!-- specific to Folder -->
  <!-- 0 or more Feature elements -->
</Folder>

Description

A Folder is used to arrange other Features hierarchically (Folders, Placemarks, NetworkLinks, or Overlays). A Feature is visible only if it and all its ancestors are visible.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Folder>
  <name>Folder.kml</name>
  <open>1</open>
  <description>
    A folder is a container that can hold multiple other objects
  </description>
  <Placemark>
    <name>Folder object 1 (Placemark)</name>
    <Point>
      <coordinates>-122.377588,37.830266,0</coordinates>
    </Point>
  </Placemark>
  <Placemark>
    <name>Folder object 2 (Polygon)</name>
    <Polygon>
      <outerBoundaryIs>
        <LinearRing>
          <coordinates>
            -122.377830,37.830445,0
            -122.377576,37.830631,0
            -122.377840,37.830642,0
            -122.377830,37.830445,0
          </coordinates>
        </LinearRing>
      </outerBoundaryIs>
    </Polygon>
  </Placemark>
  <Placemark>
    <name>Folder object 3 (Path)</name>
    <LineString>
      <tessellate>1</tessellate>
      <coordinates>
        -122.378009,37.830128,0 -122.377885,37.830379,0
      </coordinates>
    </LineString>
  </Placemark>
</Folder>
</kml>

Extends

• <Container>

Contains

• Any element derived from <Feature>

<Geometry>

Syntax

<!-- abstract element; do not create -->
<!-- Geometry id="ID" -->                 <!-- Point,LineString,LinearRing,
                                               Polygon,MultiGeometry,Model -->
<!-- /Geometry -->

Description

This is an abstract element and cannot be used directly in a KML file. It provides a placeholder object for all derived Geometry objects.

Extends

• <Object>

Extended By

• <Point>
• <LineString>
• <LinearRing>
• <Polygon>
• <MultiGeometry>
• <Model>

<GroundOverlay>

Syntax

<GroundOverlay id="ID">
  <!-- inherited from Feature element -->
  <name>...</name>                      <!-- string -->
  <visibility>1</visibility>            <!-- boolean -->
  <open>0</open>                        <!-- boolean -->
  <atom:author>...<atom:author>         <!-- xmlns:atom -->
  <atom:link>...</atom:link>            <!-- xmlns:atom -->
  <address>...</address>                <!-- string -->
  <xal:AddressDetails>...</xal:AddressDetails>  <!-- xmlns:xal -->
  <phoneNumber>...</phoneNumber>        <!-- string -->
  <Snippet maxLines="2">...</Snippet>   <!-- string -->
  <description>...</description>        <!-- string -->
  <AbstractView>...</AbstractView>      <!-- Camera or LookAt -->
  <TimePrimitive>...</TimePrimitive>
  <styleUrl>...</styleUrl>              <!-- anyURI -->
  <StyleSelector>...</StyleSelector>
  <Region>...</Region>
  <Metadata>...</Metadata>              <!-- deprecated in KML 2.2 -->
  <ExtendedData>...</ExtendedData>      <!-- new in KML 2.2 -->

  <!-- inherited from Overlay element -->
  <color>ffffffff</color>                   <!-- kml:color -->
  <drawOrder>0</drawOrder>                  <!-- int -->  
  <Icon>...</Icon>

  <!-- specific to GroundOverlay -->
  <altitude>0</altitude>                    <!-- double -->
  <altitudeMode>clampToGround</altitudeMode>
     <!-- kml:altitudeModeEnum: clampToGround or absolute --> 
  <LatLonBox>
    <north>...</north>                      <! kml:angle90 -->
    <south>...</south>                      <! kml:angle90 -->
    <east>...</east>                        <! kml:angle180 -->
    <west>...</west>                        <! kml:angle180 -->
    <rotation>0</rotation>                  <! kml:angle180 -->
  </LatLonBox>
</GroundOverlay>

Description

This element draws an image overlay draped onto the terrain. The <href> child of <Icon> specifies the image to be used as the overlay. This file can be either on a local file system or on a web server. If this element is omitted or contains no <href>, a rectangle is drawn using the color and size defined by the screen overlay.

Elements Specific to GroundOverlay

<altitude>

Specifies the distance above the earth's surface, in meters, and is interpreted according to <altitudeMode>.

<altitudeMode>

Specifies how the <altitude>is interpreted. Possible values are

• clampToGround - (default) Indicates to ignore the altitude specification and drape the overlay over the terrain.
• absolute - Sets the altitude of the overlay relative to sea level, regardless of the actual elevation of the terrain beneath the element. For example, if you set the altitude of an overlay to 10 meters with an absolute altitude mode, the overlay will appear to be at ground level if the terrain beneath is also 10 meters above sea level. If the terrain is 3 meters above sea level, the overlay will appear elevated above the terrain by 7 meters.

<LatLonBox>

Specifies where the top, bottom, right, and left sides of a bounding box for the ground overlay are aligned.

• <north> Specifies the latitude of the north edge of the bounding box, in decimal degrees from 0 to ±90.
• <south> Specifies the latitude of the south edge of the bounding box, in decimal degrees from 0 to ±90.
• <east> Specifies the longitude of the east edge of the bounding box, in decimal degrees from 0 to ±180. (For overlays that overlap the meridian of 180° longitude, values can extend beyond that range.)
• <west> Specifies the longitude of the west edge of the bounding box, in decimal degrees from 0 to ±180. (For overlays that overlap the meridian of 180° longitude, values can extend beyond that range.)
• <rotation> Specifies a rotation of the overlay about its center, in degrees. Values can be ±180. The default is 0 (north). Rotations are specified in a counterclockwise direction.

<LatLonBox>
   <north>48.25475939255556</north>
   <south>48.25207367852141</south>
   <east>-90.86591508839973</east>
   <west>-90.8714285289695</west>
   <rotation>39.37878630116985</rotation>
</LatLonBox> 

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<GroundOverlay>
   <name>GroundOverlay.kml</name>
   <color>7fffffff</color>
   <drawOrder>1</drawOrder>
   <Icon>
      <href>http://www.google.com/intl/en/images/logo.gif</href>
      <refreshMode>onInterval</refreshMode>
      <refreshInterval>86400</refreshInterval>
      <viewBoundScale>0.75</viewBoundScale>
   </Icon>
   <LatLonBox>
      <north>37.83234</north>
      <south>37.832122</south>
      <east>-122.373033</east>
      <west>-122.373724</west>
      <rotation>45</rotation>
   </LatLonBox>
</GroundOverlay>
</kml>

Extends

• <Feature>
• <Overlay>

Contained By

• <Document>
• <Folder>

<Icon>

Syntax

<Icon id="ID">
  <!-- specific to Icon -->
  <href>...</href>                      <!-- anyURI -->
  <refreshMode>onChange</refreshMode>   
    <!-- kml:refreshModeEnum: onChange, onInterval, or onExpire -->   
  <refreshInterval>4</refreshInterval>  <!-- float -->
  <viewRefreshMode>never</viewRefreshMode> 
    <!-- kml:viewRefreshModeEnum: never, onStop, onRequest, onRegion -->
  <viewRefreshTime>4</viewRefreshTime>  <!-- float -->
  <viewBoundScale>1</viewBoundScale>    <!-- float -->
  <viewFormat>...</viewFormat>          <!-- string -->
  <httpQuery>...</httpQuery>            <!-- string -->
  </Icon>

Description

Defines an image associated with an Icon style or overlay. <Icon> has the same child elements as <Link>. The required <href> child element defines the location of the image to be used as the overlay or as the icon for the placemark. This location can either be on a local file system or a remote web server.

<Icon>
  <href>Sunset.jpg</href>
</Icon>

Elements Specific to Icon

<href>

An HTTP address or a local file specification used to load an icon.

<x>, <y>, <w>, <h>

Use of these elements within <Icon> has been deprecated.

<refreshMode>

For a description of <refreshMode> and the other elements listed below, see <Link>.

<refreshInterval>

<viewRefreshMode>

<viewRefreshTime>

<viewBoundScale>

<viewFormat>

<httpQuery>

Contained By

• <GroundOverlay>
• <ScreenOverlay>
• <IconStyle>

<IconStyle>

Syntax

<IconStyle id="ID">
  <!-- inherited from ColorStyle -->
  <color>ffffffff</color>            <!-- kml:color -->
  <colorMode>normal</colorMode>      <!-- kml:colorModeEnum:normal or random -->

  <!-- specific to IconStyle -->
  <scale>1</scale>                   <!-- float -->
  <heading>0</heading>               <!-- float -->
  <Icon>
    <href>...</href>
  </Icon> 
  <hotSpot x="0.5"  y="0.5" 
    xunits="fraction" yunits="fraction"/>    <!-- kml:vec2 -->                    
</IconStyle>

Description

Specifies how icons for point Placemarks are drawn, both in the Places panel and in the 3D viewer of Google Earth. The <Icon> element specifies the icon image. The <scale> element specifies the x, y scaling of the icon. The color specified in the <color> element of <IconStyle> is blended with the color of the <Icon>.

Elements Specific to IconStyle

<scale>

Resizes the icon.

Note: The <geomScale> tag has been deprecated. Use <scale> instead.

<heading>

Direction (that is, North, South, East, West), in degrees. Default=0 (North). (See diagram.) Values range from 0 to 360 degrees.

<Icon>

A custom Icon. In <IconStyle>, the only child element of <Icon> is <href>:

• <href>: An HTTP address or a local file specification used to load an icon.

<hotSpot x="0.5" y="0.5" xunits="fraction" yunits="fraction">

Specifies the position within the Icon that is "anchored" to the <Point> specified in the Placemark. The x and y values can be specified in three different ways: as pixels ("pixels"), as fractions of the icon ("fraction"), or as inset pixels ("insetPixels"), which is an offset in pixels from the upper right corner of the icon. The x and y positions can be specified in different ways—for example, x can be in pixels and y can be a fraction. The origin of the coordinate system is in the lower left corner of the icon.

• x - Either the number of pixels, a fractional component of the icon, or a pixel inset indicating the x component of a point on the icon.
• y - Either the number of pixels, a fractional component of the icon, or a pixel inset indicating the y component of a point on the icon.
• xunits - Units in which the x value is specified. A value of fraction indicates the x value is a fraction of the icon. A value of pixels indicates the x value in pixels. A value of insetPixels indicates the indent from the right edge of the icon.
• yunits - Units in which the y value is specified. A value of fraction indicates the y value is a fraction of the icon. A value of pixels indicates the y value in pixels. A value of insetPixels indicates the indent from the top edge of the icon.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
   <Style id="randomColorIcon">
      <IconStyle>
         <color>ff00ff00</color>
         <colorMode>random</colorMode>
         <scale>1.1</scale>
         <Icon>
            <href>http://maps.google.com/mapfiles/kml/pal3/icon21.png</href>
         </Icon>
      </IconStyle>
   </Style>
   <Placemark>
      <name>IconStyle.kml</name>
      <styleUrl>#randomColorIcon</styleUrl>
      <Point>
         <coordinates>-122.36868,37.831145,0</coordinates>
      </Point>
   </Placemark>
</Document>
</kml>

Extends

• <ColorStyle>

Contained By

• <Style>

Contains

• <href> as a child of <Icon>

<kml>

Syntax

<kml xmlns="http://www.opengis.net/kml/2.2" hint="target=sky"> ... </kml>

Description

The root element of a KML file. This element is required. It follows the xml declaration at the beginning of the file. The hint attribute is used as a signal to Google Earth to display the file as celestial data.

The <kml> element may also include the namespace for any external XML schemas that are referenced within the file.

A basic <kml> element contains 0 or 1 Feature and 0 or 1 NetworkLinkControl:

<kml xmlns="http://www.opengis.net/kml/2.2">
  <NetworkLinkControl> ... </NetworkLinkControl>
  <!-- 0 or 1 Feature elements -->
</kml>

<LabelStyle>

Syntax

<LabelStyle id="ID">
  <!-- inherited from ColorStyle -->
  <color>ffffffff</color>            <!-- kml:color -->
  <colorMode>normal</colorMode>      <!-- kml:colorModeEnum: normal or random -->

  <!-- specific to LabelStyle -->
  <scale>1</scale>                   <!-- float -->
</LabelStyle>

Description

Specifies how the <name> of a Feature is drawn in the 3D viewer. A custom color, color mode, and scale for the label (name) can be specified.

Note: The <labelColor> tag is deprecated. Use <LabelStyle> instead.

Specific to <LabelStyle>

<scale>

Resizes the label.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
   <Style id="randomLabelColor">
      <LabelStyle>
         <color>ff0000cc</color>
         <colorMode>random</colorMode>
         <scale>1.5</scale>
      </LabelStyle>
   </Style>
   <Placemark>
      <name>LabelStyle.kml</name>
      <styleUrl>#randomLabelColor</styleUrl>
      <Point>
         <coordinates>-122.367375,37.829192,0</coordinates>
      </Point>
   </Placemark>
</Document>
</kml>

Extends

• <ColorStyle>

Contained By

• <Style>

<LinearRing>

Syntax

<LinearRing id="ID">
  <!-- specific to LinearRing -->
  <extrude>0</extrude>                       <!-- boolean -->
  <tessellate>0</tessellate>                 <!-- boolean -->
  <altitudeMode>clampToGround</altitudeMode> 
    <!-- kml:altitudeModeEnum: clampToGround, relativeToGround, or absolute -->
  <coordinates>...</coordinates>             <!-- lon,lat[,alt] tuples --> 
</LinearRing>

Description

Defines a closed line string, typically the outer boundary of a Polygon. Optionally, a LinearRing can also be used as the inner boundary of a Polygon to create holes in the Polygon. A Polygon can contain multiple <LinearRing> elements used as inner boundaries.

Note: In Google Earth, a Polygon with an <altitudeMode> of clampToGround follows the great circle; however, a LinearRing (by itself) with an <altitudeMode> of clampToGround follows lines of constant latitude.

Elements Specific to LinearRing

<extrude>

Boolean value. Specifies whether to connect the LinearRing to the ground. To extrude this geometry, the <altitudeMode> must be either relativeToGround or absolute, and the altitude component within the <coordinates> element must be greater than 0 (that is, in the air). Only the vertices of the LinearRing are extruded, not the center of the geometry. The vertices are extruded toward the center of the Earth's sphere.

<tessellate>

Boolean value. Specifies whether to allow the LinearRing to follow the terrain. To enable tessellation, the value for <altitudeMode> must be clampToGround. Very large LinearRings should enable tessellation so that they follow the curvature of the earth (otherwise, they may go underground and be hidden).

<altitudeMode>

Specifies how altitude components in the <coordinates> element are interpreted. Possible values are

• clampToGround - (default) Indicates to ignore an altitude specification (for example, in the <coordinates> tag).
• relativeToGround - Sets the altitude of the element relative to the actual ground elevation of a particular location. For example, if the ground elevation of a location is exactly at sea level and the altitude for a point is set to 9 meters, then the elevation for the icon of a point placemark elevation is 9 meters with this mode. However, if the same coordinate is set over a location where the ground elevation is 10 meters above sea level, then the elevation of the coordinate is 19 meters. A typical use of this mode is for placing telephone poles or a ski lift.
• absolute - Sets the altitude of the coordinate relative to sea level, regardless of the actual elevation of the terrain beneath the element. For example, if you set the altitude of a coordinate to 10 meters with an absolute altitude mode, the icon of a point placemark will appear to be at ground level if the terrain beneath is also 10 meters above sea level. If the terrain is 3 meters above sea level, the placemark will appear elevated above the terrain by 7 meters. A typical use of this mode is for aircraft placement.

<coordinates> (required)

Four or more tuples, each consisting of floating point values for longitude, latitude, and altitude. The altitude component is optional. Do not include spaces within a tuple. The last coordinate must be the same as the first coordinate. Coordinates are expressed in decimal degrees only.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Placemark>
  <name>LinearRing.kml</name>
  <Polygon>
    <outerBoundaryIs>
      <LinearRing>
        <coordinates>
          -122.365662,37.826988,0 
          -122.365202,37.826302,0 
          -122.364581,37.82655,0 
          -122.365038,37.827237,0 
          -122.365662,37.826988,0 
        </coordinates>
      </LinearRing>
    </outerBoundaryIs>
  </Polygon>
</Placemark>
</kml>

Extends

• <Geometry>

Contained By

• <MultiGeometry>
• <Placemark>
• <innerBoundaryIs>
• <outerBoundaryIs>

<LineString>

Syntax

<LineString id="ID">
  <!-- specific to LineString -->
  <extrude>0</extrude>                   <!-- boolean -->
  <tessellate>0</tessellate>             <!-- boolean -->
  <altitudeMode>clampToGround</altitudeMode> 
    <!-- kml:altitudeModeEnum: clampToGround, relativeToGround, or absolute -->
  <coordinates>...</coordinates>         <!-- lon,lat[,alt] -->
</LineString>

Description

Defines a connected set of line segments. Use <LineStyle> to specify the color, color mode, and width of the line. When a LineString is extruded, the line is extended to the ground, forming a polygon that looks somewhat like a wall or fence. For extruded LineStrings, the line itself uses the current LineStyle, and the extrusion uses the current PolyStyle. See the KML Tutorial for examples of LineStrings (or paths).

Elements Specific to LineString

<extrude>

Boolean value. Specifies whether to connect the LineString to the ground. To extrude a LineString, the value for <altitudeMode> must be either relativeToGround or absolute, and the altitude component within the <coordinates> element must be greater than 0 (that is, in the air). The vertices in the LineString are extruded toward the center of the Earth's sphere.

<tessellate>

Boolean value. Specifies whether to allow the LineString to follow the terrain. To enable tessellation, the value for <altitudeMode> must be clampToGround. Very large LineStrings should enable tessellation so that they follow the curvature of the earth (otherwise, they may go underground and be hidden).

<altitudeMode>

Specifies how altitude components in the <coordinates> element are interpreted. Possible values are

• clampToGround - (default) Indicates to ignore an altitude specification (for example, in the <coordinates> tag).
• relativeToGround - Sets the altitude of the element relative to the actual ground elevation of a particular location. For example, if the ground elevation of a location is exactly at sea level and the altitude for a point is set to 9 meters, then the elevation for the icon of a point placemark elevation is 9 meters with this mode. However, if the same coordinate is set over a location where the ground elevation is 10 meters above sea level, then the elevation of the coordinate is 19 meters. A typical use of this mode is for placing telephone poles or a ski lift.
• absolute - Sets the altitude of the coordinate relative to sea level, regardless of the actual elevation of the terrain beneath the element. For example, if you set the altitude of a coordinate to 10 meters with an absolute altitude mode, the icon of a point placemark will appear to be at ground level if the terrain beneath is also 10 meters above sea level. If the terrain is 3 meters above sea level, the placemark will appear elevated above the terrain by 7 meters. A typical use of this mode is for aircraft placement.

<coordinates> (required)

Two or more coordinate tuples, each consisting of floating point values for longitude, latitude, and altitude. The altitude component is optional. Insert a space between tuples. Do not include spaces within a tuple.

Example

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>LineString.kml</name>
  <open>1</open>
  <LookAt>
    <longitude>-122.36415</longitude>
    <latitude>37.824553</latitude>
    <altitude>0</altitude>
    <range>150</range>
    <tilt>50</tilt>
    <heading>0</heading>
  </LookAt>
  <Placemark>
    <name>unextruded</name>
    <LineString>
      <extrude>1</extrude>
      <tessellate>1</tessellate>
      <coordinates>
        -122.364383,37.824664,0 -122.364152,37.824322,0 
      </coordinates>
    </LineString>
  </Placemark>
  <Placemark>
    <name>extruded</name>
    <LineString>
      <extrude>1</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>relativeToGround</altitudeMode>
      <coordinates>
        -122.364167,37.824787,50 -122.363917,37.824423,50 
      </coordinates>
    </LineString>
  </Placemark>
</Document>
</kml>

Extends

• <Geometry>

Contained By

• <MultiGeometry>
• <Placemark>

<LineStyle>

Syntax

<LineStyle id="ID">
  <!-- inherited from ColorStyle -->
  <color>ffffffff</color>            <!-- kml:color -->
  <colorMode>normal</colorMode>      <!-- colorModeEnum: normal or random -->

  <!-- specific to LineStyle -->
  <width>1</width>                   <!-- float -->
</LineStyle>

Description

Specifies the drawing style (color, color mode, and line width) for all line geometry. Line geometry includes the outlines of outlined polygons and the extruded "tether" of Placemark icons (if extrusion is enabled).

Elements Specific to LineStyle

<width>

Width of the line, in pixels.

Example

The following example shows a 50 percent opaque red line with a width of 4 pixels.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>LineStyle.kml</name>
  <open>1</open>
  <Style id="linestyleExample">
    <LineStyle>
      <color>7f0000ff</color>
      <width>4</width>
    </LineStyle>
  </Style>
  <Placemark>
    <name>LineStyle Example</name>
    <styleUrl>#linestyleExample</styleUrl>
    <LineString>
      <extrude>1</extrude>
      <tessellate>1</tessellate>
      <coordinates>
        -122.364383,37.824664,0 -122.364152,37.824322,0 
      </coordinates>
    </LineString>
  </Placemark>
</Document>
</kml>

Extends

• <ColorStyle>

Contained By

• <Style>

<Link>

Syntax

<Link id="ID">
  <!-- specific to Link -->
  <href>...</href>                      <!-- string -->
  <refreshMode>onChange</refreshMode>   
    <!-- refreshModeEnum: onChange, onInterval, or onExpire -->   
  <refreshInterval>4</refreshInterval>  <!-- float -->
  <viewRefreshMode>never</viewRefreshMode> 
    <!-- viewRefreshModeEnum: never, onStop, onRequest, onRegion -->
  <viewRefreshTime>4</viewRefreshTime>  <!-- float -->
  <viewBoundScale>1</viewBoundScale>    <!-- float -->
  <viewFormat>BBOX=[bboxWest],[bboxSouth],[bboxEast],[bboxNorth]</viewFormat>
                                        <!-- string -->
  <httpQuery>...</httpQuery>            <!-- string -->
</Link>

Description

<Link> specifies the location of any of the following:

• KML files fetched by network links
• Image files used in any Overlay
• Model files used in the <Model> element

The file is conditionally loaded and refreshed, depending on the refresh parameters supplied here. Two different sets of refresh parameters can be specified: one set is based on time (<refreshMode> and <refreshInterval>) and one is based on the current "camera" view (<viewRefreshMode> and <viewRefreshTime>). In addition, Link specifies whether to scale the bounding box parameters that are sent to the server (<viewBoundScale> and provides a set of optional viewing parameters that can be sent to the server (<viewFormat>) as well as a set of optional parameters containing version and language information.

When a file is fetched, the URL that is sent to the server is composed of three pieces of information:

• the href (Hypertext Reference) that specifies the file to load.
• an arbitrary format string that is created from (a) parameters that you specify in the <viewFormat> element or (b) bounding box parameters (this is the default and is used if no <viewFormat> element is included in the file).
• a second format string that is specified in the <httpQuery> element.

If the file specified in <href> is a local file, the <viewFormat> and <httpQuery> elements are not used.

The <Link> element replaces the <Url> element of <NetworkLink> contained in earlier KML releases and adds functionality for the <Region> element (introduced in KML 2.1). In Google Earth releases 3.0 and earlier, the <Link> element is ignored.

Elements Specific to Link

<href>

A URL (either an HTTP address or a local file specification). When the parent of <Link> is a NetworkLink, <href> is a KML file. When the parent of <Link> is a Model, <href> is a COLLADA file. When the parent of <Link> is an Overlay, <href> is an image. Relative URLs can be used in this tag and are evaluated relative to the enclosing KML file.

<refreshMode>

Specifies a time-based refresh mode, which can be one of the following:

• onChange - refresh when the file is loaded and whenever the Link parameters change (the default).
• onInterval - refresh every n seconds (specified in <refreshInterval>).
• onExpire - refresh the file when the expiration time is reached. If a fetched file has a NetworkLinkControl, the <expires> time takes precedence over expiration times specified in HTTP headers. If no <expires> time is specified, the HTTP max-age header is used (if present). If max-age is not present, the Expires HTTP header is used (if present). (See Section RFC261b of the Hypertext Transfer Protocol - HTTP 1.1 for details on HTTP header fields.)

<refreshInterval>

Indicates to refresh the file every n seconds.

<viewRefreshMode>

Specifi