KML File Documentation

Summary

A KML file stores geographic data in Keyhole Markup Language, a plain-text XML grammar for map features: placemarks, lines, polygons, image overlays and 3D views. Google Earth is its native home, and any tool that reads .kml also reads the zipped variant .kmz. Its MIME type is application/vnd.google-earth.kml+xml. Because it is text, you can also open it in any editor to read the raw markup.

Technical details

FeatureValue
Full nameKeyhole Markup Language
File extension.kml
MIME typeapplication/vnd.google-earth.kml+xml
Format typeXML text (geographic annotation and visualisation)
DeveloperKeyhole, Inc.; acquired by Google in 2004
Maintained byOpen Geospatial Consortium (OGC)
Introduced2004 (as Google Earth’s native format)
StandardOGC KML 2.2, adopted 2008
Open standardYes
Character encodingUTF-8 XML
Root element with namespace http://www.opengis.net/kml/2.2
Coordinate orderlongitude,latitude[,altitude]
Reference systemWGS 84 (EPSG:4326)
Magic numberNone — text file; identify by the root (KMZ is a ZIP: 50 4B 03 04)
Compressed variant.kmz (ZIP holding doc.kml plus referenced images)
Geometry typesPoint, LineString, LinearRing, Polygon, Model, MultiGeometry
Related extensions.kmz, .gpx, .geojson, .shp, .gml
Specificationogc.org/standard/kml
Structure at a glance

A KML file is UTF-8 XML with no binary signature. It opens with the XML declaration , then a root that declares xmlns="http://www.opengis.net/kml/2.2". Features live inside or containers; each holds one geometry (, or ) whose are written longitude,latitude,altitude. Identify the file by that root, not a byte offset. A KMZ is the same data zipped, so it starts with the ZIP signature 50 4B 03 04 instead.

What is a KML file?

KML is short for Keyhole Markup Language, an XML grammar for describing geographic features so a mapping application can draw them: pins, lines, filled areas, image overlays draped on the terrain, 3D models and saved camera viewpoints. It was created by Keyhole, Inc. for its EarthViewer product. Google bought Keyhole in 2004, EarthViewer became Google Earth, and KML became its native save format. In 2008 the Open Geospatial Consortium adopted KML 2.2 as an open international standard, so it is no longer a Google-only format even though Google Earth remains its most common reader. The MIME type is application/vnd.google-earth.kml+xml.

A .kml file is plain UTF-8 XML, which means you can read and edit it in any text editor, but it is verbose and easy to break by hand. Every file is a tree of nested elements under a single root. The sections below describe that tree element by element: the namespace, the feature and container elements, how coordinates are written, how styling is separated from geometry, and how a KMZ packages the whole thing into one ZIP.

The kml root and the 2.2 namespace

A well-formed KML file begins with the XML declaration and then the root element. The root is always , and it must declare the KML namespace so a parser knows which vocabulary the elements belong to.



  
    ...

The namespace URI http://www.opengis.net/kml/2.2 is the OGC-standardised version; older Google files used http://earth.google.com/kml/2.x URIs, which readers still accept. Google-specific extensions (such as for time-stamped GPS tracks) live in a second namespace, conventionally bound to the prefix gx as http://www.google.com/kml/ext/2.2. Because KML is XML, the usual rules apply: elements are case-sensitive (Placemark, not placemark), every open tag needs a close tag, and the whole file must be a single rooted tree. That strictness is why a stray unescaped & in a description can stop Google Earth loading the file.

Features, folders and documents

KML separates containers from features. A container groups things; a feature is a thing shown on the map. The two container elements are and . A is the usual top-level container: it can hold shared