KML Reference Errata and Addendum

$[address]	To include property address in the balloon
$[description]	To include property description in the balloon
$[geDirections]	To include To here - From here driving directions in the balloon
$[id]	To include property id in the balloon
$[name]	To include property name in the balloon
$[phoneNumber] [1]	To include property address in the balloon
$[snippet] [1]	To include property snippet in the balloon
$[Snippet] [2]	To include property Snippet in the balloon

1. $[phoneNumber] and $[snippet] are undocumented BalloonStyle entities implemented in Google Earth.
2. Entity names are case-sensitive so $[Snippet] cannot be interchangeable with $[snippet].
   For consistency Snippet and snippet entities should be interchangeable (but currently they are not) and refer to the Snippet or snippet element (which are mutually exclusive) in the respective feature, whichever is defined.

For example, below is a coordinate string for a LineString that innocently enough looks fine, but it breaks two rules in the KML spec. Click here for the KML example.

The KML 2.2 Specification and Google KML Reference documentation are both clear on the rules of coordinates:

1. Insert whitespace between tuples
2. Do *not* include whitespace within a tuple

The author of this KML should have instead correctly formatted the coordinate as following KML snippet, which conforms to the standard:

 <LineString>
  <altitudeMode>absolute</altitudeMode>
  <coordinates>
    -81.9,29.9,0.0
    -81.9,29.9,567.8
  </coordinates>
 </LineString>

But strangely enough Google Earth versions 4.x and 5.x ignored whitespace within tuples and discarded the extra coma after the first tuple showing the line where the author had intended.

The problem is that to a machine the coordinate is ambiguous and could be interpreted in multiple ways and a straight-forward parser tokenizing on whitespace fails to parse this correctly. Google Earth just so happened to interpret it such a way that it worked.

Another problem is that the KML XML Schema validates coordinate strings as a kml:coordinatesType with this simple definition:

  <simpleType name="coordinatesType">
    <list itemType="string"/>
  </simpleType>

  <coordinates>
    -81.9,0,0
    29.9,0,0
    0,0,0
    -81.9,0,0
    29.9,0,0
    567.8,0,0
  </coordinates>

This should be a good argument for the need of stronger validation. Additional validation best practices can be found here.

Here is an example:

<description>
  <![CDATA[
This is an image
<img src="icon.jpg">
  ]]>
</description>

<description>
This is an image
&lt;img src="icon.jpg"&gt;
</description>

To display "<href> foo.kml </href>" as a literal string you would write the following using either ASCII codes or hex codes to represent the special characters:

<description>
  <![CDATA[
  1. Character entity encoding using ASCII code for special characters:
	&#60;href&#62; foo.kml &#60;/href&#62;
  <P>
  2. Character entity encoding using hex code for special characters:
	&#x3C;href&#x3E; foo.kml &#x3C;/href&#x3E;
  ]]>
</description>

However, what is not documented is that the representations other than dateTime have implicit meaning for the fields that are not specified such that just specifying only the year using the gYear type (e.g. 1997 is equivalent to 1997-01-01 T 00:00:00Z). Any date or time represents the exact instant for that time even if the full month, day of month or time is not specified. And likewise the date (YYYY-MM-DD) type implies the time at 00:00:00Z.

Note this contradicts the W3C XML Schema definitions for which the KML types are derived from. For example, gYear is defined “specifically, it is a set of one-year long, non-periodic instances; e.g. lexical 1999 to represent the whole year 1999” and likewise gYearMonth spans the whole month.

 <TimeSpan id="t1">
  <begin>1999</begin> 
  <end>2000</end>
 </TimeSpan>

 <TimeSpan id="t2">
  <begin>1999-01-01T00:00:00Z</begin> 
  <end>2000-01-01T00:00:00Z</end>
 </TimeSpan>

See also time inheritance discussed in the next topic.

“... the value of the following Feature elements shall be inherited by all Feature members of a hierarchy unless overruled by the presence of such elements locally [list includes TimePrimitive]. Inheritance of these elements continues to any depth of nesting, but if overruled by a local declaration, then the new value is inherited by all its children in turn.”

Source: http://portal.opengeospatial.org/files/?artifact_id=27810

While this was not implemented correctly in Google Earth 5.0.x, it was, however, fixed in 5.1.3509.4636 (beta). It is no longer a Google Earth defect, but the Google's KML Reference should reflect this paragraph from the OGC document so misinterpretations can be avoided.

The specification and KML Reference do not specify that it should use ZIP 2.0 or "legacy" compatible compression only (i.e. stored or deflate method), otherwise the .kmz file might not uncompress in all geobrowsers (including Google Earth). Using the more advanced compression methods (e.g., bzip2, LZMA, etc.) will not be compatible. These are undocumented implementation details.

As of April 2013, a Google Maps help center article was updated to reflect this information.

*UPDATE*

KMZ has been included in Annex C of the OGC KML 2.3 with this information as of August 2015. The author of this errata worked with OGC technical working group to incorporate a description of KMZ into the specification.

Following table shows examples that match (meaning the target NetworkLink opens in Google Earth) and those that do not.

The value of the "NetworkLink Link href" column is exactly as the entry would appear in the Link href tag, so example 1 would appear in root KML file as this:

<NetworkLink>
    <Link>
        <href>test 1.kml</href>
    </Link>
</NetworkLink>

1. Whitespace is disallowed within the URI syntax (see section 2.4.3 in http://www.ietf.org/rfc/rfc2396.txt)
   Technically the URI "test 1.kml" in example 1 is not valid, but this works as you would expect in Google Earth and the link loaded correctly.

2. The URI in example 2 "test%202.kml" is properly URL encoded with whitespace encoded as %20 string, but notice to match the zip entry, it must match exactly and the zip entry is identical to the URL-encoded form.

3. The URI in example 3 "test%203.kml" is encoded in same fashion in example 2, but it doesn't match the target zip entry which is "test 3.kml".
   This means the relative URIs for corresponding entries in KMZ files are matched as-is and no URL decoding is applied.

4. URI in example 4 "test 4.kml" does not exactly match the KMZ entry "test%204.kml" so the Link fails to load.

Recommendation: Keep it simple and avoid using whitespace and special characters in paths or filenames for entries within KMZ files.

  <complexType name="AbstractFeatureType" abstract="true">
    ...
          <choice>
            <annotation>
              <documentation>Snippet deprecated in 2.2</documentation>
            </annotation>
            <element ref="kml:Snippet" minOccurs="0"/>
            <element ref="kml:snippet" minOccurs="0"/>
          </choice>
  </complexType>

  <element name="snippet" type="string"/>

  <element name="Snippet" type="kml:SnippetType"/>
    <complexType final="#all" name="SnippetType">
        <simpleContent>
            <extension base="string">
                <attribute default="2" name="maxLines" type="int" use="optional"/>
            </extension>
        </simpleContent>
  </complexType>

The corrected changes to the schema should be the following:

<element name="north" type="kml:angle90Type" default="90.0"/>
<element name="south" type="kml:angle90Type" default="-90.0"/>

Fortunately, this is not an issue with Google Earth since it requires north and south child elements on a LatLonAltBox and LatLonBox otherwise the Region is not active or the GroundOverlay is not drawn.

What is affected is that XML Schema-based validation will not flag KML files with out-of-range north and south values (greater than 90 and less than -90) and KML libraries using the Schema-driven defaults may use the out of range defaults for these values if the elements are missing.

However, the kml:east > kml:west constraint doesn't hold if GroundOverlay LatLonBox bounds cross anti-meridian (i.e., west >= 0 AND east < 0) in which case this rule needs clarification.

For example, let west = [Korea] +125 lon, east = [California,US] -115 lon

east > west constraint is valid only if bounds don't cross anti-meridian (i.e., west < 0 OR east >= 0)

The east > west assertion in ATC 11 is invalid if bounds GroundOverlay LatLonBox bounds cross anti-meridian as in above example and must add the condition (west < 0 OR east >= 0) to be correct.

OGC KML Test Suite document should be changed in ATC 11 assertion to:

kml:east > kml:west *only if* kml:west < 0 OR kml:east >= 0

However, the Google Earth Pro user interface has some restrictions with many of the KML tags that the user cannot create and/or edit directly. Note that "Google Earth" as referenced in notes below explicitly refers to Google Earth Pro (Desktop version) unless otherwise noted. Google Earth Web, a separate Google Earth product, has many more limitations of editing KML tags but creation support is actively being added. The following lists some of these restrictions where the end-user must edit the raw KML to use some elements of the KML specification. Most of these limitations are for the lesser used or "advanced" KML features. KML developers should be aware of what Google Earth can and cannot do as a KML authoring tool and create their KML accordingly.

• address
• AddressDetails
• atom:author
• atom:link
• BalloonStyle
• drawOrder
• ExtendedData
• GroundOverlay
• hotSpot
• IconStyle
• Link
• Model
• MultiGeometry
• NetworkLink
• NetworkLinkControl
• Polygon
• Region
• Schema
• ScreenOverlay
• Snippet
• StyleMap
• tessellate
• TimeSpan
• TimeStamp
• visibility

<address>

The address represents an unstructured address written as a standard street, city, state address, and/or as a postal code. See <address>.

The address is usually added automatically in search results when you perform a search and it is displayed in the Placemark's description balloon. However, you cannot change the address or add it to a placemark if it doesn't already exist unless you edit the raw KML.

<xal:AddressDetails>

The xal:AddressDetails element is a structured address formatted in the eXtensible Address Language (xAL). See <xal:AddressDetails>.

Google Earth Pro populates address and optionally the AddressDetails elements as a result of a search, but you must edit the raw KML to add/edit this element.

<atom:author>

The atom:author element is data about the author of the KML file. See <atom:author>.

This information is displayed in geo search results in Google Earth, but to add/edit this field you must edit the raw KML.

<atom:link>

The atom:link specifies the URL of the website containing this KML or KMZ file. See <atom:link>.

This information is displayed in geo search results in Google Earth, but to add/edit this field you must edit the raw KML.

<BalloonStyle>

The BalloonStyle specifies how the description balloon for placemarks is drawn. See <BalloonStyle>.

The BalloonStyle is handled as expected by Google Earth but the client does not expose the BalloonStyle. End-users cannot edit the BalloonStyle or add it without editing the raw KML.

<drawOrder> and <gx:drawOrder>

The drawOrder and gx:drawOrder specify the stacking order for drawing overlapping ground overlays and lines or polygons, respectively. See <drawOrder> and <gx:drawOrder>.

The drawOrder option only appears in the edit placemark dialog under altitude tab if the geometry is a Polygon or GroundOverlay. However, the drawOrder option does not appear if the geometry is a LineString or MultiGeometry for placemarks or for a ScreenOverlay. In case of a LineString, MultiGeometry or ScreenOverlay, the end-user must edit the raw KML to insert/edit the drawOrder values.

Note that drawOrder in Google KML Reference documentation^[3] only mentions overlays and lines (polygons are not even mentioned). Further, handling of drawOrder on polygons is separate from that of lines and a polygon with higher drawOrder is not drawn on top of a line with a lower drawOrder value. Lines are always drawn on top of polygons regardless of the drawOrder.

<ExtendedData>

The ExtendedData element offers techniques for adding custom data to a KML Feature. See <ExtendedData>.

1. Having either untyped data/values or typed fields using the <Schema> element can appear in the description balloon, but the user cannot edit nor add ExtendedData to a new KML Feature. These can only be edited or added to the raw KML. Note: Google Earth Pro creates Schema/ExtendedData elements when it imports CSV files, but the ExendedData elements cannot be edited directly in the client.

   On a related note, if the KML Feature has ExtendedData but no description then the description popup shows the fields in an formatted HTML table form. If user tries to edit the description property then the description field is shown as empty, which can be confusing to a user unaware of the KML Feature using ExtendedData.

2. ExtendedData also allows arbitrary XML Data (explicit non-KML namespace) to associate with a Feature. See Adding Arbitrary XML Data to a Feature.

   Google Earth preserves this data, but does not process it nor does it allow the user to view/edit the contents via the Google Earth client. The data exists as metadata possibly showing the association of the feature to its source or provider. Such data could be utilized by custom applications that can parse the KML and use it accordingly. This powerful capability is not used very often and considered to be used by advanced KML developers so Google Earth client does not expose this to the end user.

<GroundOverlay>

GroundOverlay element draws an image overlay draped onto the terrain. See <GroundOverlay>.

Some "advanced" elements of the GroundOverlay are hidden from the user in the Google Earth client. See Link element for details.

<hotSpot>

The hotSpot tag specifies the position within the Icon that is "anchored" to the <Point> specified in the Placemark. See <hotSpot>.

The hotSpot offsets for standard Google Icons is automatically calculated so the icons appear in the correct orientation with respect to the location on the map. The user must specify this only if custom icons are used in which case the KML author is expected to produce the raw KML since hotspot tags cannot be added or edited using the Google Earth client for custom icons.

<IconStyle>

IconStyle specifies how icons for point Placemarks are drawn. See <IconStyle>.

With the exception of hotSpot discussed above, the only other property of the IconStyle not editable in Google Earth is the heading element.

Example

<IconStyle>
	<heading>45</heading>
	<Icon>
		<href>http://maps.google.com/mapfiles/kml/shapes/airports.png</href>
	</Icon>
</IconStyle>

Adding or editing the heading requires editing the raw KML. This is one of those lesser used elements of KML, which can be very useful to show aircraft or ship heading with just the icon.

<Link>

The Link specifies the location of Model, NetworkLink and Overlay resources. See <Link>.

The httpQuery and viewFormat elements, which are part of the <Link> element, cannot be added or edited without changing the raw KML. The details of a Link (e.g. as used in NetworkLink) is typically part of a KML feed so this is often created by a KML developer making a KML feed available.

<Model>

Model specify 3D objects described in a COLLADA file. See <Model>.

Some "advanced" elements of the Model are hidden from the user in the Google Earth client. See Link element for details.

<MultiGeometry>

A container for zero or more geometry primitives associated with the same feature. See <MultiGeometry>.

In some context such as searching, the result will be a MultiGeometry but user cannot create a multi-geometry from scratch using the create placemark tools. Editing is limited to the first item of the MultiGeometry. Full access requires editing the raw KML.

<NetworkLink>

NetworkLink references a KML file or KMZ archive on a local or remote network.

Some "advanced" elements of the NetworkLink are hidden from the user in the Google Earth client. See Link element for details.

<NetworkLinkControl>

Controls the behavior of files fetched by a <NetworkLink>. See <NetworkLinkControl>.

These elements are handled as expected by Google Earth but the client does not expose the NetworkLinkControl element. End-users cannot edit the NetworkLinkControl or add it without editing the raw KML. NetworkLinkControl (like regions) in particular are "advanced" and error-prone so hiding this from the typical user of Google Earth is not unreasonable.

<Polygon>

A Polygon is defined by an outer boundary and 0 or more inner boundaries. See <Polygon>.

You can create the outer boundary of Polygons in Google Earth, but you cannot directly create or edit the inner boundaries of a polygon without editing the raw KML.

For example, here is a KML polygon with inner boundaries.

<Region>

A region contains a bounding box that describes an area of interest defined by geographic coordinates and altitudes. See <Region>.

Regions are handled as expected by Google Earth but the client does not expose the Region element. End-users cannot edit the Region or add it without editing the raw KML.

Regions (and NetworkLinkControl) in particular are advanced and easily misused so hiding this from the typical user of Google Earth is not unreasonable but a "region" tab in Google Earth would be very helpful for advanced KML authors. The ability to show an outline of the region on the map in "edit" mode would be a time saver. Maybe this could be a feature of Google Earth Pro.

A workaround is to create an Image Overlay (aka Ground overlay) outlining the region of interest then manually edit the KML. The technique is described in this tutorial.

<Schema>

Schema specifies a custom KML schema that is used to add custom data to KML Features. See <Schema>.

The Schema in conjunction with ExtendedData element are rendered in Google Earth but end-user cannot directly edit the Schema without editing the raw KML. Google Earth Pro will automatically produce Schema and ExtendedData elements for some data when imported (e.g. ESRI shape files) in the KML that is generated.

<ScreenOverlay>

ScreenOverlay draws an image overlay fixed to the screen. See <ScreenOverlay>.

The ScreenOverlay element is rendered in Google Earth but end-user cannot create a ScreenOverlay and the x/y position cannot be edited.

<Snippet>

The Snippet overrides the description which is displayed in the Places pane (in the Sidebar) under the name of the feature. See <Snippet>.

The Snippet is essential if the description is too large or rather has multimedia content which isn't appropriate to show in the Places pane. The Snippet if provided will be displayed in Places pane instead of the description but user cannot add or edit the Snippet contents. This can be confusing to a user editing a placemark in Google Earth who tries to edit the description and the Places pane doesn't reflect the change. Only looking at the raw KML would show the Snippet being used. Only the description can be changed, which is displayed as usual in the description popup.

Also entity names in BalloonStyles are case-sensitive so $[Snippet] is not interchangeable with $[snippet]. See Snippet vs snippet discussion for more details.

<StyleMap>

StyleMap element is used to provide separate normal and highlighted styles for a placemark. See <StyeMap>.

StyleMaps are created behind the scenes when applying a style to a feature, but users cannot edit the separate styles independently without changing the raw KML.

<tessellate>

tessellate specifies whether to allow the lines or polygons to follow the terrain. See <tessellate>.

The tessellate element is added to new paths or polygons that are created by default but user cannot edit tessellate element without editing the raw KML.

<TimeSpan>

TimeSpan represents an extent in time bounded by begin and end dateTimes. See <TimeSpan>.

The TimeSpan element triggers the time slider in Google Earth but user cannot edit or add the time to a Feature without editing the raw KML.

<TimeStamp>

TimeStamp represents a single moment in time. See <TimeStamp>.

The TimeStamp element as with TimeSpan triggers the time slider in Google Earth but user cannot edit or add the time to a Feature without editing the raw KML.

<visibility>

visibility specifies whether a feature is drawn when it is initially loaded. See <visibility>.

The handling of visibility in how it cascades to children via inheritance is probably the only one or a few details in the Google Earth implementation that contradicts the OGC KML specification. In related discussions for this it was reported that what got in the OGC KML spec was wrong but in either case there is a discrepancy.

The OGC KML 2.2 Standard (OGC 07-147r2 9.1.3.2.1) states "in order for a Feature to be visible, the kml:visibility tag of all its ancestors shall also be set to 1 or true." ^[1]
So the following example would imply that the Placemark named "A" would not be visible when it is loaded in Google Earth since its ancestor's visibility is not set to 1 or "true".

Example

<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>   
      <visibility>0</visibility>
      <Placemark>
        <name>A</name>        
        <Point>
          <coordinates>-0.119824,51.511129</coordinates>
        </Point>
      </Placemark>    
  </Document>
</kml>

However, the reverse is true and this placemark is visible in Google Earth.

Google Earth implements visibility such that visibility on a child element overrides visbility even if the visibility is not explicitly defined and this violates the standard as stated above. By default the visibility value is 1 or true so to hide all children in a Folder or Document, all of the children must explicitly have visibility 0 rather than just setting it once at the Folder/Document level.

This was reported as a bug in 2009 and Google responded “Visibility has always been overridden on the child element level, and changing this would break existing code.”

Likewise there are restrictions to KML Elements Supported in Google Maps.

• Return to top of this section for full list of limitations
  
• Back to top