Usage Guide

You can find more examples in the included tests/ directory.

Build a KML from Scratch

Example how to build a simple KML file from the Python interpreter.

# Import the library
>>> from fastkml import kml
>>> from pygeoif.geometry import Polygon

# Create the root KML object
>>> k = kml.KML()
>>> ns = "{http://www.opengis.net/kml/2.2}"

# Create a KML Document and add it to the KML root object
>>> d = kml.Document(ns=ns, id="docid", name="doc name", description="doc description")
>>> k.append(d)

# Create a KML Folder and add it to the Document
>>> f = kml.Folder(ns=ns, id="fid", name="f name", description="f description")
>>> d.append(f)

# Create a KML Folder and nest it in the first Folder
>>> nf = kml.Folder(
...     ns=ns, id="nested-fid", name="nested f name", description="nested f description"
... )
>>> f.append(nf)

# Create a second KML Folder within the Document
>>> f2 = kml.Folder(ns=ns, id="id2", name="name2", description="description2")
>>> d.append(f2)

# Create a Placemark with a simple polygon geometry and add it to the
# second folder of the Document
>>> polygon = Polygon([(0, 0, 0), (1, 1, 0), (1, 0, 1)])
>>> p = kml.Placemark(
...     ns=ns, id="id", name="name", description="description", geometry=polygon
... )
>>> f2.append(p)

# Print out the KML Object as a string
>>> print(k.to_string(prettyprint=True))
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document id="docid">
    <name>doc name</name>
    <description>doc description</description>
    <Folder id="fid">
      <name>f name</name>
      <description>f description</description>
      <Folder id="nested-fid">
        <name>nested f name</name>
        <description>nested f description</description>
      </Folder>
    </Folder>
    <Folder id="id2">
      <name>name2</name>
      <description>description2</description>
      <Placemark id="id">
        <name>name</name>
        <description>description</description>
        <Polygon>
          <outerBoundaryIs>
            <LinearRing>
              <coordinates>0.000000,0.000000,0.000000 1.000000,1.000000,0.000000 1.000000,0.000000,1.000000 0.000000,0.000000,0.000000</coordinates>
            </LinearRing>
          </outerBoundaryIs>
        </Polygon>
      </Placemark>
    </Folder>
  </Document>
</kml>

Read a KML File/String

You can create a KML object by reading a KML file as a string

# Start by importing the kml module
>>> from fastkml import kml

# Setup the string which contains the KML file we want to read
>>> doc = """<kml xmlns="http://www.opengis.net/kml/2.2">
... <Document>
...   <name>Document.kml</name>
...   <open>1</open>
...   <Style id="exampleStyleDocument">
...     <LabelStyle>
...       <color>ff0000cc</color>
...     </LabelStyle>
...   </Style>
...   <Placemark>
...     <name>Document Feature 1</name>
...     <styleUrl>#exampleStyleDocument</styleUrl>
...     <Point>
...       <coordinates>-122.371,37.816,0</coordinates>
...     </Point>
...   </Placemark>
...   <Placemark>
...     <name>Document Feature 2</name>
...     <styleUrl>#exampleStyleDocument</styleUrl>
...     <Point>
...       <coordinates>-122.370,37.817,0</coordinates>
...     </Point>
...   </Placemark>
... </Document>
... </kml>"""

# Read in the KML string
>>> k = kml.KML.class_from_string(doc)

# Next we perform some simple sanity checks

# Check that the number of features is correct
# This corresponds to the single ``Document``
>>> len(k.features)
1

# (The two Placemarks of the Document)
>>> k.features[0].features  
[fastkml.features.Placemark...
>>> len(k.features[0].features)
2

# Check specifics of the first Placemark in the Document
>>> k.features[0].features[0]  
fastkml.features.Placemark(...
>>> k.features[0].features[0].description
>>> k.features[0].features[0].name
'Document Feature 1'

# Check specifics of the second Placemark in the Document
>>> k.features[0].features[1].name
'Document Feature 2'
>>> k.features[0].features[1].name = "ANOTHER NAME"

# Verify that we can print back out the KML object as a string
>>> print(k.to_string(prettyprint=True))
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>Document.kml</name>
    <open>1</open>
    <Style id="exampleStyleDocument">
      <LabelStyle>
        <color>ff0000cc</color>
      </LabelStyle>
    </Style>
    <Placemark>
      <name>Document Feature 1</name>
      <styleUrl>#exampleStyleDocument</styleUrl>
      <Point>
        <coordinates>-122.371000,37.816000,0.000000</coordinates>
      </Point>
    </Placemark>
    <Placemark>
      <name>ANOTHER NAME</name>
      <styleUrl>#exampleStyleDocument</styleUrl>
      <Point>
        <coordinates>-122.370000,37.817000,0.000000</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>