kml2geojson 6.0.0

A Python library to convert KML files to GeoJSON files

Tests:

kml2geojson is a Python package to convert KML files to GeoJSON files. It’s a lightweight, dependency-minimal, web-output-focused alternative to GDAL. Most of its code is a translation into Python of the Node.js package togeojson, but kml2geojson also adds the following features.

• Preserve KML object styling, such as color and opacity

• Optionally create a style dictionary cataloging all the KML styles used, including styles referenced through StyleMaps

• Optionally create several GeoJSON FeatureCollections, one for each KML folder present

• Optionally build a tree of Features that preserves nested KML folder structure

• Convert GroundOverlays and NetworkLinks to Features alongside Placemarks

• Convert typed ExtendedData via KML Schemas

Authors

• Alex Raichev (2015-10-03), maintainer

Installation

Install from PyPI via, say, uv add kml2geojson.

Usage

Use as a library or from the command line. For instructions on the latter, type k2g --help.

Documentation

The documentation is built via Sphinx from the source code in the docs directory then published at Codeberg Pages.

Contributing

If you want to help develop this project, here is some background reading.

• The KML reference

• Python’s Minimal DOM implementation, which this project uses to parse KML files

Notes

• This project’s development status is Beta.

• This project uses semantic versioning.

• If you would like to fund additional features to this project, feel free to email me.

• Thanks to MRCagney for periodically donating to this project.

• Constructive feedback and contributions are welcome. Please issue pull requests from a feature branch into the develop branch and include tests.

Maintainer Notes

• After pushing to master, update the published docs via uv run make -C docs publish-docs

Changes

6.0.0, 2026-07-06

• Brought feature extraction to parity with @tmcw/togeojson v7, while keeping this package’s reusable style catalog approach.

• Added StyleMap resolution to the style catalogs, with a style_map_key option to choose the ‘normal’ or ‘highlight’ pair.

• Added LabelStyle and richer IconStyle extraction (color, opacity, scale, heading, hot spot offset) and a new public function build_style.

• Fixed the bug where an IconStyle wiped previously collected line and polygon styles in the same Style element.

• Fixed opacity conversion to divide alpha by 255 instead of 256.

• Added GroundOverlay support for LatLonBox (with rotation) and gx:LatLonQuad via the new function build_ground_overlay.

• Added NetworkLink support (without fetching linked files) via the new function build_network_link.

• Added typed ExtendedData conversion via KML Schema SimpleFields and the new function build_schema.

• Added TimeStamp extraction into a timeStamp property.

• Added extraction of address, phoneNumber, open, and visibility properties, with visibility converted to a boolean.

• Added HTML-flagged descriptions for CDATA description content, following togeojson’s convention.

• Added the new function build_feature_tree to preserve nested KML folder structure.

• Breaking change: track times moved from a times property to a coordinateProperties property, following the geojson-coordinate-properties convention.

• Breaking change: features without geometry are now kept with a null geometry by default; use the new skip_null_geometry option to drop them.

• Breaking change: geometry extraction now considers only direct geometry children of a Placemark, closes unclosed polygon rings, converts bare LinearRings to LineStrings, converts single-coordinate tracks to Points, and skips degenerate geometries.

• Breaking change: convert now returns a dictionary with the key ‘feature_collections’ and, when a style type is given, the key ‘style’, instead of a variable-shape sequence.

• Breaking change: removed the unused GEOTYPES constant and added __all__ to the main module to stop star imports leaking implementation names.

• Added the --style-map-key and --skip-null-geometry options to the k2g command line interface.

• Removed stale test fixtures that reflected the old output format.

5.1.1, 2026-03-12

• Migrated packaging metadata to PEP 621 in pyproject.toml and switch the build backend to Hatchling.

• Updated project URLs to the current repository and documentation site.

• Raised the declared minimum Python version in package metadata.

• Modernized GitHub Actions to use uv and refresh the Python test matrix.

• Updated README installation and documentation guidance.

• Fixed k2g CLI output handling for styled and unstyled conversion paths.

• Restructured tests to use one test function per API function with sectioned behavioral coverage.

• Added CLI integration tests for the no-style and styled separate-folders paths.

5.1.0, 2022-04-29

• Extended convert() to accept a KML file object.

• Added type hints.

• Updated dependencies and removed version caps.

• Dropped support for Python versions less than 3.8.

• Switched from Travis CI to Github Actions.

5.0.1, 2021-10-11

• Re-included the MIT License file and added more metadata to the file pyproject.toml for a more informative listing on PyPi.

5.0.0, 2021-10-07

• Upgraded to Python 3.9 and dropped support for Python versions < 3.6.

• Switched to Poetry.

• Breaking change: refactored the convert function to return dictionaries instead of files.

• Moved docs from Rawgit to Github Pages.

4.0.2, 2017-04-26

• Fixed the bug where setup.py could not find the license file.

4.0.1, 2017-04-22

• Moved the name of a FeatureCollection into a ‘name’ attribute, because RFC 7946 says that a GeoJSON FetaureCollection must not have a ‘properties’ attribute

• Stripped leanding and trailing whitespace from text content to avoid cluttered or blank name and description attribute values

• Switched to pytest for testing

4.0.0, 2016-11-24

• Moved command line functionality to separate module

• Renamed some functions

3.0.4, 2015-10-15

Disambiguated filenames in main().

3.0.3, 2015-10-13

Improved to_filename() again.

3.0.2, 2015-10-12

Improved to_filename() and removed the lowercasing.

3.0.1, 2015-10-12

Tweaked to_filename() to lowercase and underscore results. Forgot to do that last time.

3.0.0, 2015-10-12

Changed the output of build_layers() and moved layer names into the GeoJSON FeatureCollections

2.0.2, 2015-10-12

• Replaced underscores with dashes in command line options

2.0.1, 2015-10-12

• Set default border style for colored polygons

2.0.0, 2015-10-08

• Added documentation

• Tweaked the command line tool options

1.0.0, 2015-10-05

• Changed some names

• Added lots of tests

0.1.1, 2015-10-03

Fixed packaging to find README.rst

0.1.0, 2015-10-03

First