|
|
$[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 |
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:
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> |
|
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>If you prefer not to use the CDATA element, you can use entity references to replace the special characters:
<description> This is an image <img src="icon.jpg"> </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., <) 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: < or <
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: <href> foo.kml </href> <P> 2. Character entity encoding using hex code for special characters: <href> foo.kml </href> ]]> </description>
type | format | example |
---|---|---|
gYear | YYYY | 1997 |
gYearMonth | YYYY-MM | 1997-07 |
date | YYYY-MM-DD | 1997-07-16 |
dateTime | YYYY-MM-DDThh:mm:ssZ | 1997-07-16T07:30:15Z |
dateTime | YYYY-MM-DDThh:mm:sszzzzzz | 1997-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.
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> |
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.
“... 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.
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:
Recommendation: Keep it simple and avoid using whitespace and special characters in paths or filenames for entries within KMZ files.
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#snippetThe 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.
The corrected changes to the schema should be the following:
<element name="north" 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.
<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.
* 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
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.
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.
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.
This information is displayed in geo search results in Google Earth, but to add/edit this field you must edit the raw KML.
This information is displayed in geo search results in Google Earth, but to add/edit this field you must edit the raw KML.
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.
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.
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.
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.
Some "advanced" elements of the GroundOverlay are hidden from the user in the Google Earth client. See Link element for details.
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.
With the exception of hotSpot discussed above, the only other property of the IconStyle not editable in Google Earth is the heading element.
<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.
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.
Some "advanced" elements of the Model are hidden from the user in the Google Earth client. See Link element for details.
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.
Some "advanced" elements of the NetworkLink are hidden from the user in the Google Earth client. See Link element for details.
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.
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.
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.
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.
The ScreenOverlay element is rendered in Google Earth but end-user cannot create a ScreenOverlay and the x/y position cannot be edited.
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.
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.
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.
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.
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.
<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.
Likewise there are restrictions to KML Elements Supported in Google Maps.
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.