KML file format

What is inside a KML file

A KML file is XML. Its content sits in a <Document>, often organised in <Folder> elements. Each item on the map is a <Placemark> with a name, a description and a geometry:

• <Point> for a single place.
• <LineString> for a line, such as a route or a path.
• <Polygon> for an area.
• <MultiGeometry> for several geometries in one placemark.

Styles (<Style>) set the colours, the line widths and the icons.

Coordinates come in the order longitude, latitude, altitude, separated by commas, with a space between points. Most people expect latitude first, so a file written in the wrong order puts its points in another part of the world. Altitude is optional and in metres.

This is a short KML file with a placemark for the start and a line:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>Morning ride</name>
    <Placemark>
      <name>Start</name>
      <Point>
        <coordinates>-9.1394,38.7139,45</coordinates>
      </Point>
    </Placemark>
    <Placemark>
      <name>Morning ride</name>
      <LineString>
        <coordinates>-9.1394,38.7139,45 -9.1388,38.7142,46 -9.1381,38.7146,47</coordinates>
      </LineString>
    </Placemark>
  </Document>
</kml>

Times and sensor data in gx:Track

A <LineString> has no times. Google added its own element for recorded tracks, <gx:Track>. It pairs each position (<gx:coord>, with the three values separated by spaces) with a time (<when>). Sensor values such as heart rate or cadence can follow in <ExtendedData>, with one value per point, and Google Earth shows them in the elevation profile of the track.

TrackLoupe reads gx:Track with its times. It recognises heart rate, cadence, power, temperature and speed in the extended data by their names.

How TrackLoupe reads a KML file

• Lines and recorded tracks become tracks, and each line of a multi-geometry becomes a segment.
• Points become waypoints, with their names, descriptions and times.
• Polygons and network links are left out, and a note says how many. A network link (<NetworkLink>) loads more KML from another address. Following it would send a request from your file to another site, so TrackLoupe never does.
• Some apps write an altitude of 0 for every point when they do not know the elevation. When all the altitudes of a line are 0, TrackLoupe treats the line as having no elevation, so the profile does not show a flat line at sea level.

How to open a KML file

• In your browser: the KML viewer shows the lines and points with an elevation profile, and the file stays on your device.
• In Google Earth: Google Earth on the web imports KML and KMZ files.
• In Google My Maps: My Maps imports KML files up to 5 MB. It may drop parts of the file, such as time-based elements, multi-geometries and folders.
• In a text editor: any editor opens it, because KML is plain text.

Questions

What is a KML file used for?

It shows places, routes and areas on a map or a globe. Google Earth is the best known program that uses it, and the OGC standard makes it common in mapping software.

What is the difference between KML and KMZ?

A KMZ file is a KML file compressed in a ZIP archive, often with its icons and images. The KML vs KMZ page explains when to use each.

Can I convert a KML file to GPX here?

Not yet. A KML to GPX converter is listed under “Coming next” on the tools page. Until then, the KML viewer shows what the file holds.

Why are my KML points in the wrong place?

The coordinates may be in the wrong order. KML puts longitude first. A file written with latitude first moves every point, often into the sea or onto another continent.

Why does my KML file show nothing in the viewer?

The file may hold only polygons or a network link, which the viewer leaves out. The note above the drawing says what it skipped.