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
| Feature | Value |
|---|---|
| Full name | Keyhole Markup Language |
| File extension | .kml |
| MIME type | application/vnd.google-earth.kml+xml |
| Format type | XML text (geographic annotation and visualisation) |
| Developer | Keyhole, Inc.; acquired by Google in 2004 |
| Maintained by | Open Geospatial Consortium (OGC) |
| Introduced | 2004 (as Google Earth’s native format) |
| Standard | OGC KML 2.2, adopted 2008 |
| Open standard | Yes |
| Character encoding | UTF-8 XML |
| Root element | <kml> with namespace http://www.opengis.net/kml/2.2 |
| Coordinate order | longitude,latitude[,altitude] |
| Reference system | WGS 84 (EPSG:4326) |
| Magic number | None — text file; identify by the <kml> root (KMZ is a ZIP: 50 4B 03 04) |
| Compressed variant | .kmz (ZIP holding doc.kml plus referenced images) |
| Geometry types | Point, LineString, LinearRing, Polygon, Model, MultiGeometry |
| Related extensions | .kmz, .gpx, .geojson, .shp, .gml |
| Specification | ogc.org/standard/kml |
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 <kml> 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 <kml>, and it must declare the KML namespace so a parser knows which vocabulary the elements belong to.
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
...
</Document>
</kml>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 <gx:Track> 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 <Document> and <Folder>. A <Document> is the usual top-level container: it can hold shared <Style> definitions (referenced by ID) plus any number of features and sub-folders. A <Folder> is a simpler grouping used to build the collapsible tree you see in the Places panel.
The workhorse feature is the <Placemark>. A placemark pairs a name and description with exactly one geometry, and it is what produces a clickable item on the map. Its <name> becomes the label, its <description> (which may contain HTML inside a CDATA block) becomes the balloon that pops up when you click it, and its geometry child decides whether it draws as a point, a line or an area.
<Placemark>
<name>Trailhead</name>
<description><![CDATA[Parking and the start of the loop.]]></description>
<Point>
<coordinates>-122.0822,37.4222,0</coordinates>
</Point>
</Placemark>Point, LineString, Polygon and the coordinate order
KML defines a small set of geometry elements. <Point> is a single position (a pin). <LineString> is an open path through two or more positions (a route or river). <LinearRing> is a closed ring whose first and last positions are identical, used to build a <Polygon>. A <Polygon> has one <outerBoundaryIs> ring and any number of <innerBoundaryIs> rings that punch holes in it. <MultiGeometry> bundles several geometries into one placemark.
Every geometry ends in a <coordinates> element, and its format trips up almost everyone the first time. Coordinates are written longitude first, then latitude, then optional altitude, separated by commas, with whole tuples separated by whitespace:
<coordinates>
-122.084,37.422,0
-122.081,37.423,0
-122.079,37.421,0
</coordinates>The lon,lat order is the opposite of the lat,lon convention people speak aloud and that Google Maps search uses, which is a frequent source of points landing in the wrong hemisphere. Values are decimal degrees in the WGS 84 datum (EPSG:4326); altitude is in metres and its meaning depends on the geometry’s <altitudeMode> (clampToGround, relativeToGround or absolute). This is the same reference system used by GPX and GeoJSON, though GeoJSON also puts longitude before latitude while GPX uses named lat and lon attributes.
Styles, StyleMaps and shared styling
Geometry says where; style says how it looks. KML keeps the two separate so many features can share one appearance. A <Style> element carries sub-styles: <IconStyle> (the pin icon and colour), <LineStyle> (stroke colour and width), <PolyStyle> (fill colour and whether the outline shows) and <LabelStyle> (the text label). A style given an id can be referenced from any placemark by <styleUrl>#thatId</styleUrl>.
One detail worth knowing: KML colours are written as aabbggrr hex, that is alpha, blue, green, red, which reverses the rrggbb order used almost everywhere else on the web. So fully opaque red is ff0000ff, not ffff0000. A <StyleMap> pairs two styles under the keys normal and highlight, letting a feature change appearance on mouse-over.
Overlays and NetworkLink: images and live data
Beyond vector geometry, KML can place raster imagery and pull in remote content. A <GroundOverlay> drapes an image over a geographic box defined by north, south, east and west edges (a scanned map, a heat layer). A <ScreenOverlay> pins an image to a fixed spot on the screen regardless of where you pan (a logo or legend). Both reference their image through an <Icon><href>.
The most powerful, and the most security-relevant, element is <NetworkLink>. It makes a KML file fetch further KML from a URL when opened, optionally refreshing on a timer or as the camera moves. That is how live feeds (weather, vehicle positions) are published as a small linking file. It also means a KML from an untrusted source can quietly contact a remote server the moment you open it, which is the one real caution with an otherwise passive text format: it can act as a tracking or data-pull vector, so treat network-linked KML from strangers with the same care as any link.
KMZ: the zipped, self-contained package
Because a KML can reference external icons, overlay images and models, sharing one often means sharing a folder of files. KMZ solves that by packaging everything into a single ZIP archive, then renaming it .kmz. Inside, the main document is by convention named doc.kml at the archive root, and the referenced images sit alongside it (often in a files/ or images/ subfolder), with the KML’s <href> paths pointing at them relatively.
Since KMZ is an ordinary ZIP, it begins with the ZIP local-file-header signature 50 4B 03 04 (PK..), not with XML text, so a hex peek at the first bytes tells the two apart instantly. Any archiver can open a KMZ by unzipping it; renaming file.kmz to file.zip and extracting it yields the doc.kml you can read as plain text. In practice people use “KML” and “KMZ” almost interchangeably because the payload is identical, with KMZ just smaller and tidier for distribution.
KML alongside GPX, GeoJSON and Shapefile
KML is one of several ways to move map data between tools, and it converts cleanly to and from the others. GPX is the GPS-exchange format that Garmin devices, Strava and Komoot expect, so exporting a KML route to GPX is the common step for loading it onto a watch or bike computer. GeoJSON is the lightweight JSON standard used by web maps such as Leaflet and Mapbox. The Esri Shapefile (.shp) is the professional GIS vector format; converting KML to Shapefile flattens the rich styling KML carries, because a Shapefile stores geometry and attributes but no icons or colours. Command-line GDAL/OGR (ogr2ogr) and the free desktop app QGIS handle all of these translations, reading the same <coordinates> tuples described above and re-emitting them in the target format’s conventions.
References
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.