Quick Start
The fastest start is no install at all: drop a file on the inspector. This page covers the ikml program, for batches of files, scripts and data pipelines.
1. Get the ikml Command
Download the archive for your system from the download page, unpack it and put ikml somewhere on your PATH. Check it works:
ikml version
2. See What’s Inside
ikml inspect reads KML, KMZ and GeoJSON, whatever the file is called, and shows its structure, its attribute fields and styles, and anything worth knowing:
$ ikml inspect field-trip.kml
field-trip.kml
Format: KML, 3.4 KiB
Namespace: http://www.opengis.net/kml/2.2
Placemarks: 3
Geometry: 1 LineString, 2 Point
Coordinates: 6
Extent: lon 35.2134 to 35.2291, lat 31.7767 to 31.7801
Folders: 3
Styles: 4 Style, 2 StyleMap
Structure:
Document Field trip 2026
Folder Meeting points: 2 placemark(s); 2 Point
Folder Routes: 1 placemark(s); 1 LineString
Attribute fields:
contact 2 placemark(s) (Data)
capacity 2 placemark(s) (Data)
length_km 1 placemark(s) (Data)
Styles:
Style #icon-1899-0288D1-normal used by 0: icon https://www.gstatic.com/mapspro/images/stock/503-wht-blank_maps.png, label
Style #icon-1899-0288D1-highlight used by 0: icon https://www.gstatic.com/mapspro/images/stock/503-wht-blank_maps.png, label
StyleMap #icon-1899-0288D1 used by 2: normal #icon-1899-0288D1-normal, highlight #icon-1899-0288D1-highlight
Style #line-E65100-3000-normal used by 0: line
Style #line-E65100-3000-highlight used by 0: line
StyleMap #line-E65100-3000 used by 1: normal #line-E65100-3000-normal, highlight #line-E65100-3000-highlight
Issues:
INFO remote-ref Style 'icon-1899-0288D1-normal' (line 12)
2 references to files on www.gstatic.com, first here. They load from the
internet and are not inside the file.
0 error(s), 0 warning(s), 1 note(s).
3. Check It
ikml check prints only the problems and sets the exit status: 0 when there are no errors, 1 when there are, 2 when the file couldn’t be read at all.
$ ikml check plots.kml
plots.kml (kml, 588 bytes)
ERROR swapped-latlon
Every placemark in the file (3) has latitude and longitude in the wrong
order: the first value of each point is within ±90 and the second is
outside it. A swapped point lands on the far side of the world.
1 error(s), 0 warning(s), 0 note(s).
Each problem has a code, such as swapped-latlon. The reference lists them all. Add --json for scripts, and --strict to treat warnings as errors too.
4. Convert It and See What It Costs
ikml convert picks the output format from the file name, .geojson, .kml or .kmz. With --report it says what the conversion loses, keeps in another form or changes:
$ ikml convert field-trip.kml field-trip.geojson --report
Converted field-trip.kml (kml) to field-trip.geojson (geojson, 768 bytes).
What changes from kml to geojson:
[CHANGED] Styles and colors (3)
GeoJSON has no styling. 3 placemarks use 2 shared styles. iKML keeps
line color and width, fill color and opacity, and marker color as
simplestyle-spec properties (stroke, stroke-width, stroke-opacity, fill,
fill-opacity, marker-color) for 3 of them. Mapbox, geojson.io and GitHub
read these; most other tools ignore them.
[LOST] Style details with no GeoJSON equivalent (3)
These have no simplestyle-spec property and are dropped: icon images (2
placemarks), icon hotspots (2), label color and scale (2), highlight
styles from 2 StyleMaps.
[KEPT] Folder structure (2)
GeoJSON is a flat list of features, so 2 folders are flattened. iKML
keeps each placemark's folder path in a "folder" property (for example
"Survey / Gates"), and converting back to KML rebuilds the folders.
[LOST] Folder and document descriptions (1)
Descriptions on folders and documents have no place in GeoJSON.
[KEPT] Attribute data (ExtendedData) (5)
5 ExtendedData values become feature properties.
[KEPT] Descriptions (1)
1 description is kept in a "description" property. 1 contains HTML,
which stays HTML; GeoJSON viewers may show it as plain text.
[LOST] Tessellate (1)
Lines that follow the terrain are a KML display setting with no GeoJSON
equivalent.
Before: 0 error(s), 0 warning(s). After: 0 error(s), 0 warning(s).
5. Clean It
ikml clean applies safe fixes and lists every one. The original file isn’t touched:
$ ikml clean plots.kml plots-fixed.kml --fix-swapped --report
Cleaned plots.kml (kml) to plots-fixed.kml (kml, 586 bytes).
Changes (3):
swapped-latlon Swapped longitude and latitude back into the right order.
at Placemark 'Depot North' (line 5)
swapped-latlon Swapped longitude and latitude back into the right order.
at Placemark 'Depot South' (line 9)
swapped-latlon Swapped longitude and latitude back into the right order.
at Placemark 'Supply line' (line 13)
Nothing is lost converting kml to kml.
Before: 1 error(s), 0 warning(s). After: 0 error(s), 0 warning(s).
Swapping latitude and longitude only happens with --fix-swapped, because a wrong guess moves data a long way. iKML only reports a swap when it’s certain: every point has a first value inside ±90 and a second outside it, which no real longitude-latitude pair can have.
6. In a Pipeline
Because check sets its exit status, a script can refuse files before they reach a database:
for f in incoming/*.km[lz] incoming/*.geojson; do
ikml check "$f" --json > "reports/$(basename "$f").json" || mv "$f" rejected/
done