KML4Earth


Reference

© Copyright 2011 jasonm1

logo KML Reference Errata and Addendum  

The Open Geospatial Consortium (OGC) KML 2.2 Standard [OGC 07-147r2] has a few areas that are not fully defined. There exist a few inconsistencies between the Google KML Reference, the Google Earth™ implementation, and the OGC KML Standard. There are also subtle differences between versions of Google Earth in its interpretation of KML.

The official OGC KML 2.2 Standard (07-147r2) supersedes both Google KML 2.2 Reference and a related KML 2.2 Reference - An OGC Best Practice (07-113r1) document so if any conflict exists, the official KML standard is assumed correct.

OGC KML 2.3 Standard (12-007r2) was recently published and cleans up many of the areas that were not clearly defined in the KML 2.2 specification. Google Earth does not yet support the new KML 2.3 features.

This page documents some of these issues to promote discussions on issues related to interoperability and fill in gaps in the KML standard.

There are also some undocumented elements and limitations in Google Earth that are listed here.

Table of contents:
  1. BalloonStyle Entity Replacement
  2. Strict validation of KML
  3. Encoding Special Characters in KML
  4. Representing time in KML
  5. Inheritance
  6. KMZ
  7. Snippet vs snippet
  8. LatLonAltBox discrepency
  9. LatLonBox assertion
  10. Limitations of Google Earth with respect to KML
  11. Reference
If there are any errors in this document or something missing please feel free to contact me and share your suggestion.

Special thanks to Barry Hunter for some additions to the limitations of Google Earth list.


1. BalloonStyle Entity Replacement

BalloonStyle entity replacement is clearly defined in the Google KML Reference, but only mentioned in the OGC KML 2.2 Specification [section 6.5] as an example that includes $[name] and $[description] and the full list is not defined. Likewise, it is still only mentioned in an example in the OGC KML 2.3 Specification.

The following entities are defined in KML as implemented in Google Earth:
$[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
Notes:
  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.

2. Strict validation of KML

Google Earth literally bends over backwards to parse loosely defined KML files that have elements out of order, wrong XML encoding, KML files labeled as KMZ files, and so forth. Of special note is badly formatted and ambiguous coordinates which prior to Google Earth 6.0 were allowed.

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.
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>
Nowhere does the KML XML Schema restrict tuples of longitude and latitude as decimal degrees in the range -180,+180 and -90,+90 respectively. So a value such as "a,b,c d,e,f" would validate correctly using only XML Schema-based validation.

This, however, changed as of Google Earth 6.0, which now interprets the coordinates element accordingly to the strict rules mentioned above so this badly formed coordinate gets normalized and rewritten as the following:
  <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>
  • When opened in Google Earth these two tuples now get converted into six tuples.

  • Each whitespace in the coordinates value marks the start of a new tuple and each value in our example becomes the longitude with a latitude and altitude set at zero.

  • Notice the sixth tuple with 567.8 as the longitude clearly not in the valid +/- 180 range.
Google Earth version 6.1 and higher gives no error or warning, but it does show a portion of the line segment in a different hemisphere. If the line's altitudeMode value is changed to clampToGround then you will see the line wrap around most of the globe - clearly not what the original KML author had in mind. Click here for the full example KML.

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

3. Encoding Special Characters in KML

The KML 2.2 Specification[1] and Google KML Reference[3] state you must use XML entity/character references or the CDATA element to escape angle brackets, apostrophes, and other special characters.

Here is an example:

<description>
  <![CDATA[
This is an image
<img src="icon.jpg">
  ]]>
</description>
If you prefer not to use the CDATA element, you can use entity references to replace the special characters:
<description>
This is an image
&lt;img src="icon.jpg"&gt;
</description>
What is not defined is how to encode angle brackets, apostrophes, and special characters to appear as-is in the HTML display. Suppose you want to show some raw KML or XML tags to display in the description rather than be used to markup the text. The entity references (e.g., &lt;) within the CDATA block does not work for this. To show raw markup in the description you must use character entities with the ASCII or hex code for the special characters. To display a less than sign (<) you must use: &#60; or &#x3C;

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>

4. Representing time in KML

KML can represent dates and time in its features. The time can be a TimeStamp or TimeSpan using the kml:dateTimeType structure allowing for an absolute time using the ISO-8601 dateTime format or several date variations as defined in following table:
typeformatexample
gYear YYYY1997
gYearMonth YYYY-MM1997-07
date YYYY-MM-DD1997-07-16
dateTime YYYY-MM-DDThh:mm:ssZ1997-07-16T07:30:15Z
dateTimeYYYY-MM-DDThh:mm:sszzzzzz1997-07-16T10:30:15+03:00

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.

Illustrated example:

Example 1:
 <TimeSpan id="t1">
  <begin>1999</begin> 
  <end>2000</end>
 </TimeSpan>
Example 2:
 <TimeSpan id="t2">
  <begin>1999-01-01T00:00:00Z</begin> 
  <end>2000-01-01T00:00:00Z</end>
 </TimeSpan>
The first TimeSpan (example 1) in KML fragment above begins at 1999 and ends at 2000 does not represent the whole year for 2000, but for the instant the calendar becomes 2000 on January 1st and is equivalent to the second TimeSpan (example 2). The XML Schema definition would instead represent the first time period (1999-2000) as 1999-01-01 to 2000-12-31 not 1999-01-01 to 2000-01-01 as implemented in Google Earth so this is a discrepancy.

Try out the provided example to see for yourself. The target "A" placemark has a start and end time as 1999 and 2000 respectively as in example 1 above. The "1" placemark has the start and end time with absolute time as in example 2. Click on the marker "B" placemark to change the time window from 2000-12-01 to 2000-12-31, which will in turn hide the "A" and "1" placemarks showing that they are equivalent.

See also time inheritance discussed in the next topic.

5. Inheritance

Time is defined on Features in the Google KML Reference, but time on nested features is not clearly defined there. If a placemark is a child element of a Document or Folder that has a Timespan or Timestamp when does it become visible? Does it make a difference if the placemark itself has a Timespan or Timestamp? It wasn't clear how these cases are interpreted from the KML unless you refer to section 9.6.2 of the OGC KML 2.2 standard which describes the AbstractContainerGroup and the correct behavior of inherited time.

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

6. KMZ

6.1 KMZ Supported Compression methods

KMZ is briefly defined in the OGC KML 2.2 Specification as a ZIP-compressed KML file in the introduction.[1]

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.

6.2 NetworkLinks relative URLs and KMZ entries

Having whitespace and special characters in paths or filenames of entries inside a KMZ file should be avoided to ensure it's interoperable across all platforms and all KML viewers. Google Earth, for example, requires a strict exact match between NetworkLink target href URLs and the corresponding KMZ zip entry. Other KML/Earth Viewers may handle whitespace and URL encoding differently.

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

Example NetworkLink Link href KMZ zip entry Link works
1. test 1.kml test 1.kml Yes
2. test%202.kml test%202.kml Yes
3. test%203.kml test 3.kml No
4. test 4.kml test%204.kml No

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>
Examples explained:

  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.

7. Snippet vs snippet

The KML specification and associated XML Schema clearly show the element "Snippet" form deprecated and "snippet" as the approved form to use:

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

However, the Google Earth documentation only shows the deprecated "Snippet" form of kml:SnippetType:

https://developers.google.com/kml/documentation/kmlreference#snippet
The examples in the Google KML Reference documentation and related samples also show the element Snippet as well.

Google Earth, fortunately, supports both forms of snippet and Snippet. However, note that if you use the $[Snippet] substitution entity in a BalloonStyle text then it must exactly match the capitalization of Snippet or snippet as used the KML placemark. So if you use Snippet in your KML then must use $[Snippet] to reference it in the BalloonStyle. The substitution entities in the BalloonStyle text are case-sensitive so $[Snippet] and $[snippet] cannot be used interchangeably. This behavior is undocumented.

This issue has been reported to Google in July 2010 and likewise to the OGC as feedback to the KML 2.2 specification. Note that Galdos Systems, who is the organization that runs the KML validator web site and chaired the KML 2.2 working group, documents in their KML validation suite as ATC 76 where Snippet is deprecated and warns at the informational level if found in KML files.

In cases of contradition, the official OGC KML 2.2 Standard supersedes the Google KML Reference so kml:snippet is the recommended form.

See also the Snippet limitations in Google Earth.

8. LatLonAltBox discrepency

The OGC KML 2.2 specification and associated XML Schema defines latitude, and the north/south components of a kml:LatLonAltBox used in Regions and kml:LatLonBox used in GroundOverlay as the following:

<element name="latitude" type="kml:angle90Type" default="0.0"/>
<element name="north" type="kml:angle180Type" default="180.0"/>
<element name="south" type="kml:angle180Type" default="-180.0"/>

Simply put, north and south fields are optional in the Region/LatLonAtBox and GroundOverlay/LatLonBox elements and north and south types are of the "kml:angle180Type" type whose default values are +180, -180 respectively, but the spec states that north and south valid values (which should represent the Latitude min/max bounds) are in the range 0 to 90 not 180 so the default values are out of the valid range.

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"/>
The relevant sections in the OGC KML spec (OGC 07-147r2) can be found in 9.14.3 where the description is correct with a valid range from -90 to 90 but then lists the type as angle180Type.

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.

9. LatLonBox assertion

The KML 2.2 - Abstract Test Suite: OGC document: # 07-134r2 defines following test assertion:

ATC 11: LatLonBox states following constraints:

 * kml:north > kml:south
 * kml:east > kml:west

Pass if the assertion is satisfied; fail otherwise. The default envelope for a kml:GroundOverlay is the entire surface of the WGS 84 ellipsoid.
By testing north > south and east > west, we are testing for a non-zero area.

Reference: OGC-07-147r2: cl. 11.3.2

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

10. Limitations of Google Earth with respect to KML

Google Earth supports the full KML 2.2 specification with which it can parse and render.

However, the Google Earth client user interface (including Google Earth Pro) has some restrictions with many of the KML tags that the user cannot create and/or edit. 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>
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 raw KML.

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

Currently, Google Earth does not use the AddressDetails element. It uses <address> instead. With the exception of Google Earth Pro that populates both the AddressDetails and address elements as result of a search, you still 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.

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


Reference

  1. OGC KML Standard (Specification and related documents)
    http://www.opengeospatial.org/standards/kml

  2. KML Best Practice (Validation, tools, metadata, and more)
    http://kml4earth.appspot.com/kmlBestPractice.html

  3. Google KML Reference
    https://developers.google.com/kml/documentation/kmlreference

  4. KML Validator service
    http://www.kmlvalidator.com/home.htm

Google Earth (TM) and Google Maps (TM) are registered trademarks of Google Inc. KML4Earth is not affiliated with Google.
KML4Earth is not an official source of information on Google or Google Earth. But, we try to get reliable information whenever we can.

Created and maintained by jasonm1