---
name: kml
displayName: KML/KMZ Reader & Converter
description: Read, inspect, and convert .kml and .kmz files to JSON or CSV. Use
  when opening a KML/KMZ file, extracting placemarks, or exporting geospatial
  data to another format.
tags:
  - geospatial
  - kml
  - kmz
  - converter
  - reader
  - gis
capabilities:
  - ReadKml
  - ReadKmz
  - ConvertToCsv
  - ConvertToJson
  - ConvertToGeoJson
  - ExtractPlacemarks
  - SummarizeFeatures
representativeQueries:
  - Read a .kml file and show me its contents
  - Convert KML to CSV
  - Extract all placemarks from a KMZ file
  - Convert KML to GeoJSON
  - What placemarks are in this .kml file?
version: 0.1.0
tier: curated
---

# KML/KMZ Reader & Converter

Read, inspect, and convert `.kml` and `.kmz` files using only the Python standard library (`xml.etree.ElementTree` + `zipfile`). Handles Placemarks with Points, LineStrings, Polygons, and MultiGeometry. Extracts ExtendedData attributes and converts to CSV or JSON.

## When to use

- You have a `.kml` or `.kmz` file and need to inspect its placemarks and geometry.
- You want to export placemark names, descriptions, attributes, and coordinates to CSV for spreadsheet or database use.
- You need a JSON representation of all placemarks for downstream processing.
- You want to understand the structure of an unfamiliar KML/KMZ export.

## Steps

1. **Detect format.** Check the file extension: `.kml` is plain XML; `.kmz` is a ZIP archive containing a root `.kml` entry.
2. **Route by task.**
   - To read/inspect: parse the XML, traverse the Folder/Document/Placemark tree, and print a human-readable summary of placemark count, geometry types, and the first N placemarks.
   - To convert to CSV: collect all attribute keys from ExtendedData across all placemarks, write one row per placemark with name, description, geometry type, first-coordinate, and all extended attributes.
   - To convert to JSON: serialize each placemark as a JSON object with name, description, geometry, and attributes; output as a JSON array.
3. **Run the script.** Use `scripts/kml_convert.py` with the file path argument and an optional `--format` flag.

## Operations

| Capability | CRUD | Resource | Tool |
|---|---|---|---|
| ReadKml | READ | .kml file | scripts/kml_convert.py |
| ReadKmz | READ | .kmz archive | scripts/kml_convert.py |
| ExtractPlacemarks | READ | Placemark elements | scripts/kml_convert.py |
| SummarizeFeatures | READ | Placemark tree | scripts/kml_convert.py |
| ConvertToCsv | READ + local CREATE | CSV output | scripts/kml_convert.py |
| ConvertToJson | READ + local CREATE | JSON output | scripts/kml_convert.py |

## Output

- **Summary mode (default):** placemark count, geometry types present, ExtendedData keys found, and the first 5 placemarks as formatted JSON.
- **CSV mode (`--format csv`):** one row per placemark; columns are `name`, `description`, `geometry_type`, `first_coordinate`, and all discovered ExtendedData keys. Printed to stdout.
- **JSON mode (`--format json`):** a JSON array, one object per placemark, with `name`, `description`, `geometry`, and `attributes` (ExtendedData key/value dict). The `geometry` object always has a `type` field. For Point, LineString, LinearRing, and Polygon it has a `coordinates` field; for MultiGeometry it has a `geometries` field (a list of sub-geometry objects). Printed to stdout.

## Notes

- KMZ files are ZIP archives: the script opens them with `zipfile` and reads the root `.kml` entry (preferring `doc.kml`).
- Namespace handling is automatic: the script reads the XML namespace directly from the root element tag at parse time and uses whatever namespace is declared there (including KML 2.2, 2.1, or any other variant). A fallback matches Placemark elements by local name when the root and inner elements carry different namespaces.
- Coordinates follow KML order: `longitude,latitude[,altitude]` — not lat/lon.
- ExtendedData `<Data>` elements are the most common attribute pattern; `<SchemaData>/<SimpleData>` is also supported.
- Nested Folders and Documents are flattened: all Placemarks are collected regardless of depth.
- The script exits with a non-zero code and a descriptive error message on malformed XML, missing file, or invalid ZIP.

<!-- runner-fallback -->
## Remote runner (MCP)
Can't run this locally (no setup, missing dependency)? The StealthStack runner exposes the **same code** as server-side MCP tools — no local install needed: `kml_summary`, `kml_to_csv`, `kml_to_json`, `kml_to_geojson`. Call the `application/mcp` catalog twin of this skill (its `runnerTwin`).