Convert KML to CSV

KML was built to draw on a globe. A file of placemarks carries far more than positions — a style for each icon, a description balloon with HTML in it, a folder tree that groups them, sometimes a ground overlay behind them. But a great many KML files in circulation are used as a list dressed up as a map: forty branch locations, a set of survey sites, the places somebody starred in Google Earth over a year.

For that file, a CSV is the more honest container. Each placemark becomes a row of name and coordinates, which is what a geocoder, a route optimiser, a CRM import or a `GROUP BY` actually consumes. Everything that made it a drawing is left behind, and that is a deliberate loss rather than a limitation: a column for an icon URL would help nobody, and there is no column shape that survives an HTML description balloon.

KML writes a coordinate as `longitude,latitude,altitude` in a single whitespace-separated string. Nearly every other format in this family, GPX and TCX included, names latitude first, and this reversal is the single most common way a KML conversion goes wrong: the pair is transposed rather than shifted, so Berlin at 13.4, 52.5 comes out as 52.5, 13.4 and lands in the Arabian Sea.

The conversion swaps them, so the CSV columns are `latitude` then `longitude`. This is worth checking rather than trusting, and there is a one-second check: for anywhere in western Europe latitude runs from about 36 to 71 and longitude from about −10 to 30, so if the first coordinate column is small and the second is large, something upstream has swapped them back.

A KML nests. A `<Document>` contains `<Folder>` elements, which contain more folders and eventually the `<Placemark>` elements that carry the geometry. The reader walks that tree rather than looking one level down, because a KML exported from a mapping tool routinely puts its placemarks three levels deep, and a parser that only checks the top of the document reports an empty file that is in fact full.

What the walk does not do is preserve the folder structure. A pin in `Sites / Phase 2 / Confirmed` comes out as a row indistinguishable from one at the top level, because the CSV has one `name` column and it belongs to the placemark. If the grouping is the information, it has to be encoded in the placemark names before converting, or recovered from the KML afterwards.

A Placemark holding a `<Point>` becomes one row typed `waypoint`. A Placemark holding a `<LineString>` becomes a run of rows typed `track`, one per vertex, all sharing the placemark name. Those two cover the overwhelming majority of KML in circulation and both come through with their names intact.

Two things produce nothing at all, and both are worth knowing before you convert. A `<Polygon>` — a shaded region, a property boundary, a service area — keeps its outline inside nested boundary elements that this parser does not descend into, so an area contributes no rows. A `<MultiGeometry>` wrapping several lines in one placemark is skipped for the same reason. A KML made entirely of areas fails with the message that no track or waypoints were found, which is accurate and is not a file problem.

A LineString is a shape with no notion of when. If the KML came from a GPS export rather than from drawing, it may instead hold a `gx:Track`, Google's extension that stores parallel lists of `<when>` timestamps and `<coord>` positions. The reader handles it as a distinct case rather than treating it as a line, and the timestamps land in the `time` column.

The tell that you have one is that the `time` column is populated at all. If every cell in it is empty, the source held LineStrings, and no converter can recover times a file never stored. That is also the reason the third coordinate value inside a gx:Track is separated by a space rather than a comma — the same document uses two different separators for two different geometries, which is a genuine oddity of the format rather than a mistake in a file.

The third value in a KML coordinate is altitude in metres, and the conversion writes it into the `elevation` column when it is present. What it does not do is consult `<altitudeMode>`, the sibling element that says how the altitude should be interpreted — clamped to the ground, relative to it, or absolute.

That matters because Google Earth's default is `clampToGround`, under which the altitude value is ignored entirely and is very often written as `0`. So a KML drawn by hand over hilly terrain tends to produce an elevation column full of zeros that mean "on the surface", not "at sea level". Treat a column of zeros as absent rather than as data, and take elevation from a GPX or a TCX if it is the number you came for.

The output puts every `waypoint` row before every `track` row, regardless of the order they appeared in the document. That is a convenience for the common case: a KML of pins converts to a file whose rows are all waypoints, and a mixed KML of pins plus a drawn route gives you the pins at the top where they can be selected without scrolling.

The cost is that document order is not preserved across the two types. If the sequence of features in the KML carried meaning — the order a survey visited its sites, say — that ordering has to come from the placemark names or from the `time` column, not from the row numbers. Within each type, the original order is kept exactly.

Placemark names are the field most likely to break a naive CSV, because they are free text written by a person. `Warehouse 3, Rear Entrance` contains the delimiter, and an address used as a name contains several. The writer quotes any value containing a comma, a quotation mark or a newline, and doubles interior quotation marks, which is what RFC 4180 asks for and what every spreadsheet and CSV library reads back correctly.

Coordinates never need quoting, so the file stays readable in a text editor. If you are checking the output by eye, the quoted names are the rows worth glancing at: a name containing an unbalanced quotation mark in the source KML is the one case where the original file was already malformed and the conversion faithfully carries that through.

KML defines an `<address>` element on a Placemark, and Google Earth fills it in when a pin was created by searching for a place rather than by clicking on the globe. It is not read here, so the output carries a name and coordinates and nothing resembling a postal address even where the source document had one.

For most destinations that is not a loss, because a latitude and longitude is a stronger key than a street line and every routing, mapping and geocoding service accepts one directly. Where an address is genuinely required — a mailing run, a delivery manifest — it has to come from a reverse-geocoding step against the coordinates, and a handful of the results are worth checking by eye: a pin dropped in the middle of a car park resolves to whichever building is nearest, which is often not the one it was marking.

The conversion runs entirely in this browser tab — the KML is read, walked and rewritten locally, and no request carries it anywhere. There is no account, no queue and no retention policy to read, because there is nothing on a server to retain.

The reason to care is what a placemark list usually is. A KML of pins is frequently a customer list, a set of delivery addresses, patient or client sites, or the locations of assets somebody would rather not publish. Converting it to CSV makes it more portable and more readable at the same time, so the output deserves the same handling as the spreadsheet it is about to become part of.