View source for Keyhole Markup Language

{{notes}}

Note that KML is an open format, and specific apps (such as Google Earth) may not use/support all of it.

KML uses decimal lat-long, and uses WGS84. (always?{{verify}}) (see also [[Cartographic_notes]])


==Applications and associations==

KML (Keyhole Markup Language)
* MIME: <tt>application/vnd.google-earth.kml+xml</tt>
KMZ: KML-zipped
* MIME:<tt>application/vnd.google-earth.kmz</tt>
* containing a compressed KML file, 
* ...lets you pack in images (icons, etc.) so that the KML does not have to refer to public-server URIs for that


Will open in Google Earth or anything else that has it registered.

Note that Google Maps also takes KML, like:
 <nowiki>http://maps.google.com/maps?q=http://example.com/things.kml</nowiki>


===Simple example===
A simple KML file looks like:
<code lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
  <Placemark>
    <name>Portland</name>
    <Point>
      <coordinates>-122.6676358763541,45.52181645404051</coordinates>
    </Point>
  </Placemark>
</kml>
</code>

<!--
...although kml may only have one sub-element, so the structure is commonly kml/Document/(Folder/)Placemark
-->

===What is stored===
KML <tt>Feature</tt>s include:
* Placemark (basic vector features: points, lines, polygons)
* Folder, Document (containers)
** Document (container for features and styles)
** Folder (container for features)
* image overlays (ground, screen, photo)
* NetworkLink (to remote KML/KMZ files)


Note that <tt>Region</tt> is regularly used to describe metadata and points of interest within certain boxes. 

Lod allows you to specify the (minimum, maximum) screen size of a feature before it should be considered active.


====Styles====
You can declare colors and/or line widths on icons, labels, lines, polygons, balloons, and lists.

May be ignored unless you need them.

Are usually referenced by their id, within the same document.

See also:
* http://code.google.com/apis/kml/documentation/kmlreference.html#style
* http://code.google.com/apis/kml/documentation/kmlreference.html#colorstyle
* http://code.google.com/apis/kml/documentation/kmlreference.html#styleurl
* http://code.google.com/apis/kml/documentation/kmlreference.html#stylemap
* http://code.google.com/apis/kml/documentation/kmlreference.html#styleselector

====Placemarks====
* should include a &lt;name&gt; and 
* may include a &lt;description&gt; (HTML must be element-escaped, or in CDATA section)
* may include a &lt;LookAt&gt; structure
* may include a &lt;styleUrl&gt; to refer to style (usually a #hash based URL to refer to a style declared in the same KML file.
* has an element declaring its type: (Point, LineString, etc., see below)
** with option elements depending on the type
** and a &lt;coordinates&gt; element
*** with coordinates in text nodes
*** space-separated coordinates
*** comma-separated per dimensions
**** longitude (≥ −180 and <= 180)
**** latitude (≥ −90 and ≤ 90)
**** altitude (meters) (optional)



Common options:
* <tt>altitudeMode</tt> (string) 
** defines interpretation of the third (altitude) coordinate, if used:
** <tt>clampToGround</tt> (default, ignores altitude)
** <tt>relativeToGround</tt>: Relative to ground elevation
** <tt>absolute</tt>: Relative to sea level (regardless of ground elevation) 

* extrude (boolean, 0 or 1)
** connect point/line/polygon to ground (direction of center of Earth)
** applies when altitudeMode is relativeToGround or absolute

* tessellate (boolean, 0 or 1)
** Show very large line segments so they follow the terrain (vertically, rather than poking through mountains, go underground, etc.)
** applies when altitudeMode is clampToGround



====Types, options per type====
=====Point=====
* altitudeMode, extrude
* Example:  <tt>&lt;Point>&lt;coordinates>-6.1456,-35.1&lt;/coordinates>&lt;/Point></tt>

=====LineString=====
* Non-closed sequence of coordinates
* altitudeMode, extrude, tessellate

=====LinearRing=====
* Closed line string (a minimal polygon)
* altitudeMode, extrude, tessellate, 
* typically the outer boundary of a Polygon. A LinearRing can also be used as the inner boundary of a Polygon to create holes in the Polygon. A Polygon can contain multiple <LinearRing> elements used as inner boundaries.

=====Polygon=====
* Similar to LinearRing, with a required main polygon, and contained cutout polygons:
** outerBoundaryIs (LinearRing), required
** innerBoundaryIs (LinearRing), (0 or more)
* altitudeMode, extrude, tessellate


=====MultiGeometry=====
Can contain one or more Geometry-type (e.g. line, polygon) elements, that should be viewed as a single feature.

(except in cases where polygon innerBoundaries apply?)

=====Model=====
Points to a COLLADA resource (see also [[Cartographic notes]])

===See Also===
* http://code.google.com/apis/kml/documentation/kmlreference.html


* http://code.google.com/apis/kml/documentation/regions.html

* http://code.google.com/apis/kml/documentation/cameras.html


Time and animation:
* http://code.google.com/apis/kml/documentation/time.html

Expiration, Updates:
* http://code.google.com/apis/kml/documentation/expiration.html
* http://code.google.com/apis/kml/documentation/updates.html


<!--
Unsorted:
* http://zcologia.com/news/750/keytree/
-->