KML Reference (original) (raw)

Skip to main content

KML Reference

This section contains an alphabetical reference for all KML elements defined in KML Version 2.2, as well as elements in the Google extension namespace. 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.

class tree diagram

Note that abstract elements (shown in 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 ) for files loaded with a NetworkLink. It is also used by shared styles (see Pin on a mountaintop #pushpin 170.1435558771009,-43.60505741890396,0

gx:Tour Play me!

<gx:Playlist>

  <gx:FlyTo>  
    <gx:flyToMode>bounce</gx:flyToMode>  
    <gx:duration>3</gx:duration>  
    <Camera>  
      <longitude>170.157</longitude>  
      <latitude>-43.671</latitude>  
      <altitude>9700</altitude>  
      <heading>-6.333</heading>  
      <tilt>33.5</tilt>  
    </Camera>  
  </gx:FlyTo>

  **<gx:AnimatedUpdate>**

gx:duration5 10.0 

  <gx:Wait>
    <gx:duration>5</gx:duration>
  </gx:Wait>

</gx:Playlist>

Extends

Contains

Syntax

ffffffff ff000000 ... default

Description

Specifies how the description balloon for placemarks is drawn. The , 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

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 element within has been deprecated. Use instead.

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

Text displayed in the balloon. If no text is specified, Google Earth draws the default balloon (with the Feature in boldface, the Feature , 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 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 element with some content, or with $[description] to substitute the basic Feature .

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

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

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

Example

BalloonStyle.kml 1 BalloonStyle An example of BalloonStyle #exampleBalloonStyle -122.370533,37.823842,0

Extends

Contained By

Do not put shared styles within a Folder.

The following example illustrates use of a shared style.

Example

**** Document.kml 1 Document Feature 1 #exampleStyleDocument -122.371,37.816,0 Document Feature 2 #exampleStyleDocument -122.370,37.817,0 ****

Extends

Contains

Back to top

gx:duration

This element is an extension of the OGC KML 2.2 standard and is supported in Google Earth 5.0 and later. Learn more

Syntax

gx:duration0.0

Description

<gx:duration> extends gx:TourPrimitive by specifying a time-span for events. The time is written as seconds using XML's double datatype.

Duration and gx:FlyTo

When a duration is included within a <gx:FlyTo> element, it specifies the length of time that the browser takes to fly from the previous point to the specified point.

gx:FlyTo gx:flyToModebounce gx:duration10.2

...

Duration and gx:AnimatedUpdate

Specifies the length of time over which the update takes place. Integer, float, and color fields are smoothly animated from original to new value across the duration; boolean, string, and other values that don't lend to interpolation are updated at the end of the duration.

gx:AnimatedUpdate gx:duration5.0 

....

Syntax

                       

  ...   
   ...               

...   
<namespace_prefix:other>...

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

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

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 element of , the notation $[name/displayName] is replaced with . If you substitute the value of the name attribute of the element in this format (for example, $[holeYardage], the attribute value is replaced with . By default, the Placemark's balloon displays the name/value pairs associated with it.

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

Value of the data pair.

Club house 1 234 4

This element is used in conjunction with 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 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"

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

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 element.

Here is an example of defining two custom data elements:

Easy trail Pi in the sky 3.14159 10 -122.000,37.002 Difficult trail Mount Everest 347.45 10000 -122.000,37.002

<namespace_prefix:other>

This element allows you to add untyped custom data. Be sure to reference the namespace prefix in the element of your file or as an attribute of the 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:

14 2 4

Contained By

See Also

<_Feature_>

Syntax

... 1 0 atom:author...atom:author <atom:link href=" "/>

...
xal:AddressDetails...
...
... ... ... <TimePrimitive_>...</_TimePrimitive_> ... <_StyleSelector>... ... ... ...
<-- /_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

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

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 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.

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 . 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:

These elements are defined in the Atom Syndication Format. The complete specification is found at http://atompub.org. `` (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).

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

tag to specify the location of a point instead of using latitude and longitude coordinates. (However, if a is provided, it takes precedence over the
.) 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

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"

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, seehttp://www.ietf.org/rfc /rfc2806.txt.

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 are used. In Google Earth, if a Placemark contains both a description and a Snippet, the appears beneath the Placemark in the Places panel, and the appears in the Placemark's description balloon. This tag does not support HTML markup. has a maxLines attribute, an integer that specifies the maximum number of lines to display.

User-supplied content that appears in the description balloon.

The supported content for the element changed from Google Earth 4.3 to 5.0. Specific information for each version is listed out below, followed by information common to both.

Google Earth 5.0

Google Earth 5.0 (and later) supports plain text content, as well as full HTML and JavaScript, within description balloons. Contents of the description tag are rendered by the WebKit open source web browser engine, and are displayed as they would be in any WebKit-based browser.

General restrictions

Links to local files are generally not allowed. This prevents malicious code from damaging your system or accessing your data. Should you wish to allow access to your local filesystem, select Preferences > Allow access to local files and personal data. Links to image files on the local filesystem are always allowed, if contained within an tag.

Content that has been compressed into a KMZ file can be accessed, even if on the local filesystem.

Cookies are enabled, but for the purposes of the same-origin policy, local content does not share a domain with any other content (including other local content).

HTML

HTML is mostly rendered as it would be in any WebKit browser.

Targets are ignored when included in HTML written directly into the KML; all such links are opened as if the target is set to _blank. Any specified targets are ignored.

HTML that is contained in an iFrame, however, or dynamically generated with JavaScript or DHTML, will use target="_self" as the default. Other targets can be specified and are supported.

The contents of KMZ files, local anchor links, and ;flyto methods cannot be targeted from HTML contained within an iFrame.

If the user specifies width="100%" for the width of an iFrame, then the iFrame's width will be dependent on all the other content in the balloon—it should essentially be ignored while calculating layout size. This rule applies to any other block element inside the balloon as well.

JavaScript

Most JavaScript is supported. Dialog boxes can not be created - functions such as alert() and prompt() will not be displayed. They will, however, be written to the system console, as will other errors and exceptions.

CSS

CSS is allowed. As with CSS in a regular web browser, CSS can be used to style text, page elements, and to control the size and appearance of the description balloon.

Google Earth 4.3

The 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.)

Common information

If your description contains no HTML markup, Google Earth attempts to format it, replacing newlines with
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 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:

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

Other Behavior Specified Through Use of the Element

KML supports the use of two attributes within the element: href and type.

The anchor element 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:

The type attribute is used within the 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:

Defines a viewpoint associated with any element derived from Feature. See and .

Associates this Feature with a period of time () or a point in time ().

URL of a Placemark #sn_blue-dot_copy3 -93.47875999999999,45.083248,0

Extends

Extended By

gx:FlyTo

This element is an extension of the OGC KML 2.2 standard and is supported in Google Earth 5.0 and later. Learn more

Syntax

<gx:FlyTo id="ID"> gx:duration0.0 gx:flyToModebounce ...

Description

<gx:FlyTo> specifies a point in space to which the browser will fly during a tour. It must contain one AbstractView, and should contain <gx:duration> and <gx:flyToMode> elements, which specify the time it takes to fly to the defined point from the current point, and the method of flight, respectively.

gx:flyToMode

There are two allowed values for <gx:flyToMode>: smooth, and bounce.

  • Smooth FlyTos allow for an unbroken flight from point to point to point (and on). An unbroken series of smooth FlyTos will begin and end at zero velocity, and will not slow at each point. A series of smooth FlyTos is broken by any of the following elements:

    • <gx:flyToMode>bounce</gx:flyToMode>
    • <gx:Wait>
      This means that velocity will be zero at the smooth FlyTo immediately preceding either of the above elements. A series of smooth FlyTos is not broken by gx:AnimatedUpdate elements.

  • Bounce FlyTos each begin and end at zero velocity.

Example

gx:FlyTo
gx:duration2.55
gx:flyToModesmooth

-113.084448
36.567081
41277.571403
116.150227
absolute

Extends

Contains

Syntax

... 1 0 atom:author...atom:author <atom:link href=" "/>

...
xal:AddressDetails...
...
... ... ... <TimePrimitive_>...</_TimePrimitive_> ... <_StyleSelector>... ... ... ...

**</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

**** Folder.kml 1 A folder is a container that can hold multiple other objects Folder object 1 (Placemark) -122.377588,37.830266,0 Folder object 2 (Polygon) -122.377830,37.830445,0 -122.377576,37.830631,0 -122.377840,37.830642,0 -122.377830,37.830445,0 Folder object 3 (Path) 1 -122.378009,37.830128,0 -122.377885,37.830379,0 ****

Extends

Contains

<_Geometry_>

Syntax

<!_-- Geometry_ id="ID" --> <!-- /_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

Extended By

Syntax

... 1 0 atom:author...atom:author <atom:link href=" "/>

...
xal:AddressDetails...
...
... ... ... <TimePrimitive_>...</_TimePrimitive_> ... <_StyleSelector>... ... ... ...

ffffffff 0 ...

0 clampToGround ... <! kml:angle90 --> ... <! kml:angle90 --> ... <! kml:angle180 --> ... <! kml:angle180 --> 0 <! kml:angle180 --> gx:LatLonQuad ...

Description

This element draws an image overlay draped onto the terrain. The child of 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 , a rectangle is drawn using the color and LatLonBox bounds defined by the ground overlay.

Elements Specific to GroundOverlay

Specifies the distance above the earth's surface, in meters, and is interpreted according to the altitude mode.

Specifies how the 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.

gx:altitudeMode

A KML extension in the Google extension namespace, allowing altitudes relative to the sea floor. Values are:

  • relativeToSeaFloor - Interprets the as a value in meters above the sea floor. If the point is above land rather than sea, the will be interpreted as being above the ground.
  • clampToSeaFloor - The specification is ignored, and the overlay will be draped over the sea floor. If the point is on land rather than at sea, the overlay will be positioned on the ground.

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

  • Specifies the latitude of the north edge of the bounding box, in decimal degrees from 0 to ±90.
  • Specifies the latitude of the south edge of the bounding box, in decimal degrees from 0 to ±90.
  • 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.)
  • 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.)
  • 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.

48.25475939255556 48.25207367852141 -90.86591508839973 -90.8714285289695 39.37878630116985

gx:LatLonQuad

Used for nonrectangular quadrilateral ground overlays.

Example

**** GroundOverlay.kml 7fffffff 1 http://www.google.com/intl/en/images/logo.gif onInterval 86400 0.75 37.83234 37.832122 -122.373033 -122.373724 45 ****

Extends

Contained By

Syntax

... gx:x0gx:x/ gx:y0gx:y/ gx:w-1gx:w/ gx:h-1gx:h/ onChange 4 never 4 1 ... ...

Description

Defines an image associated with an Icon style or overlay. The required 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. The gx:x, gx:y, gx:w, and gx:h elements are used to select one icon from an image that contains multiple icons (often referred to as an icon palette.

Sunset.jpg

/home/mydir/myiconpalette.jpg 138 138

Elements Specific to Icon

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

gx:x

and

gx:y

If the specifies an icon palette, these elements identify the offsets, in pixels, from the lower-left corner of the icon palette.If no values are specified for x and y, the lower left corner of the icon palette is assumed to be the lower-left corner of the icon to use.

gx:w

and

gx:h

If the specifies an icon palette, these elements specify the width (gx:w) and height (gx:h), in pixels, of the icon to use.

For a description of and the other elements listed below, see .

Contained By

Syntax

ffffffff normal

1 0 ...

Description

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

Elements Specific to IconStyle

Resizes the icon.

Note: The tag has been deprecated. Use instead.

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

A custom Icon. In , the only child element of is :

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

Specifies the position within the Icon that is "anchored" to the 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

IconStyle.kml #randomColorIcon -122.36868,37.831145,0

Extends

Contained By