Reference Guide

Atom

KML 2.2 supports new elements for including data about the author and related website in your KML file. This information is displayed in geo search results, both in Earth browsers such as Google Earth, and in other applications such as Google Maps. The ascription elements used in KML are as follows:

atom:author element - parent element for atom:name atom:name element - the name of the author atom:link element - contains the href attribute href attribute - URL of the web page containing the KML/KMZ file

These elements are defined in the Atom Syndication Format. The complete specification is found at http://atompub.org.

This library only implements a subset of Atom that is useful with KML

class fastkml.atom.Author(ns: str | None = None, name_spaces: Dict[str, str] | None = None, name: str | None = None, uri: str | None = None, email: str | None = None)

Return the names one author of the feed/entry.

A feed/entry may have multiple authors.

class fastkml.atom.Contributor(ns: str | None = None, name_spaces: Dict[str, str] | None = None, name: str | None = None, uri: str | None = None, email: str | None = None)

Return the names one contributor to the feed/entry.

A feed/entry may have multiple contributor elements.

Identifies a related Web page. The rel attribute defines the type of relation. A feed is limited to one alternate per type and hreflang. <link> is patterned after html’s link element. It has one required attribute, href, and five optional attributes: rel, type, hreflang, title, and length.

Base

Abstract base classes.

Config

Frequently used constants and configuration options.

fastkml.config.register_namespaces(**namespaces: str) → None

Register namespaces for use in etree.ElementTree.parse().

fastkml.config.set_default_namespaces() → None

Register the default namespaces for use in etree.ElementTree.parse().

fastkml.config.set_etree_implementation(implementation: module) → None

Set the etree implementation to use.

Geometry

class fastkml.geometry.LineString(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, extrude: bool | None = None, tessellate: bool | None = None, altitude_mode: AltitudeMode | None = None, geometry: LineString)
etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element

Return the KML Object as an Element.

class fastkml.geometry.LinearRing(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, extrude: bool | None = None, tessellate: bool | None = None, altitude_mode: AltitudeMode | None = None, geometry: LinearRing)
class fastkml.geometry.MultiGeometry(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, extrude: bool | None = None, tessellate: bool | None = None, altitude_mode: AltitudeMode | None = None, geometry: MultiPoint | MultiLineString | MultiPolygon | GeometryCollection)
etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element

Return the KML Object as an Element.

class fastkml.geometry.Point(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, extrude: bool | None = None, tessellate: bool | None = None, altitude_mode: AltitudeMode | None = None, geometry: Point)
etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element

Return the KML Object as an Element.

class fastkml.geometry.Polygon(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, extrude: bool | None = None, tessellate: bool | None = None, altitude_mode: AltitudeMode | None = None, geometry: Polygon)
etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element

Return the KML Object as an Element.

fastkml.geometry.create_multigeometry(geometries: Sequence[Polygon | LineString | LinearRing | Point | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection]) → MultiPoint | MultiLineString | MultiPolygon | GeometryCollection | None

Create a MultiGeometry from a sequence of geometries.

Args:

geometries: Sequence of geometries.

Returns:

MultiGeometry

GX

With the launch of Google Earth 5.0, Google has provided extensions to KML to support a number of new features. These extensions use the gx prefix and the following namespace URI:

xmlns:gx="http://www.google.com/kml/ext/2.2"

This namespace URI must be added to the <kml> element in any KML file using gx-prefixed elements:

<kml
    xmlns="http://www.opengis.net/kml/2.2"
    xmlns:gx="http://www.google.com/kml/ext/2.2"
>

Extensions to KML may not be supported in all geo-browsers. If your browser doesn’t support particular extensions, the data in those extensions should be silently ignored, and the rest of the KML file should load without errors.

Elements that currently use the gx prefix are:

  • gx:altitudeMode

  • gx:altitudeOffset

  • gx:angles

  • gx:AnimatedUpdate

  • gx:balloonVisibility

  • gx:coord

  • gx:delayedStart

  • gx:drawOrder

  • gx:duration

  • gx:FlyTo

  • gx:flyToMode

  • gx:h

  • gx:horizFov

  • gx:interpolate

  • gx:labelVisibility

  • gx:LatLonQuad

  • gx:MultiTrack

  • gx:vieweroptions

  • gx:outerColor

  • gx:outerWidth

  • gx:physicalWidth

  • gx:Playlist

  • gx:playMode

  • gx:SoundCue

  • gx:TimeSpan

  • gx:TimeStamp

  • gx:Tour

  • gx:TourControl

  • gx:TourPrimitive

  • gx:Track

  • gx:ViewerOptions

  • gx:w

  • gx:Wait

  • gx:x

  • gx:y

The complete XML schema for elements in this extension namespace is located at http://developers.google.com/kml/schema/kml22gx.xsd.

class fastkml.gx.Angle(heading: float = 0.0, tilt: float = 0.0, roll: float = 0.0)

The gx:angles element specifies the heading, tilt, and roll.

The angles are specified in degrees, and the default values are 0 (heading and tilt) and 0 (roll). The angles are specified in the following order: heading, tilt, roll.

class fastkml.gx.MultiTrack(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, extrude: bool | None = None, tessellate: bool | None = None, altitude_mode: AltitudeMode | None = None, geometry: MultiLineString | None = None, tracks: Iterable[Track] | None = None, interpolate: bool | None = None)
class fastkml.gx.Track(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, extrude: bool | None = None, tessellate: bool | None = None, altitude_mode: AltitudeMode | None = None, geometry: LineString | None = None, track_items: Iterable[TrackItem] | None = None)

A track describes how an object moves through the world over a given time period.

This feature allows you to create one visible object in Google Earth (either a Point icon or a Model) that encodes multiple positions for the same object for multiple times. In Google Earth, the time slider allows the user to move the view through time, which animates the position of the object.

Tracks are a more efficient mechanism for associating time data with visible Features, since you create only one Feature, which can be associated with multiple time elements as the object moves through space.

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal, name_spaces: Dict[str, str] | None = None) → Element

Return the KML Object as an Element.

class fastkml.gx.TrackItem(when: datetime | None = None, coord: Point | None = None, angle: Angle | None = None)

A track item describes an objects position and heading at a specific time.

KML

KML is an open standard officially named the OpenGIS KML Encoding Standard (OGC KML).

It is maintained by the Open Geospatial Consortium, Inc. (OGC). The complete specification for OGC KML can be found at http://www.opengeospatial.org/standards/kml/.

The complete XML schema for KML is located at http://schemas.opengis.net/kml/.

class fastkml.kml.KML(ns: str | None = None, name_spaces: Dict[str, str] | None = None, features: Iterable[Folder | Document | Placemark | GroundOverlay | PhotoOverlay] | None = None)

represents a KML File.

append(kmlobj: Folder | Document | Placemark | GroundOverlay | PhotoOverlay) → None

Append a feature.

classmethod class_from_string(string: str, *, ns: str | None = None, name_spaces: Dict[str, str] | None = None, strict: bool = True) → _XMLObject

Create a kml object from a string.

Args:

string: String representation (serialized XML) of the kml object ns: Namespace of the element (default: None) name_spaces: Dictionary of namespace prefixes and URIs (default: None) strict: Whether to enforce strict parsing (default: True)

Returns:

Geometry object

etree_element(precision: int | None = None, verbosity: Verbosity = Verbosity.normal) → Element

Return an Element object representing the KML element.

Args:

precision (Optional[int]): The precision used for floating-point values. verbosity (Verbosity): The verbosity level for generating the KML element.

Returns:

Element: The Element object representing the KML element.

classmethod get_tag_name() → str

Return the tag name.

Styles

Once you’ve created features within Google Earth and examined the KML code Google Earth generates, you’ll notice how styles are an important part of how your data is displayed.

class fastkml.styles.BalloonStyle(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, bg_color: str | None = None, text_color: str | None = None, text: str | None = None, display_mode: DisplayMode | None = None)

Specifies how the description balloon for placemarks is drawn.

The <bgColor>, if specified, is used as the background color of the balloon.

https://developers.google.com/kml/documentation/kmlreference#balloonstyle

class fastkml.styles.IconStyle(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, color: str | None = None, color_mode: ColorMode | None = None, scale: float | None = None, heading: float | None = None, icon: Icon | None = None, hot_spot: HotSpot | None = None)

Specifies how icons for point Placemarks are drawn.

The <Icon> element specifies the icon image. The <scale> element specifies the x, y scaling of the icon. The color specified in the <color> element of <IconStyle> is blended with the color of the <Icon>.

https://developers.google.com/kml/documentation/kmlreference#iconstyle

class fastkml.styles.LabelStyle(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, color: str | None = None, color_mode: ColorMode | None = None, scale: float | None = None)

Specifies how the <name> of a Feature is drawn in the 3D viewer.

A custom color, color mode, and scale for the label (name) can be specified.

https://developers.google.com/kml/documentation/kmlreference#labelstyle

class fastkml.styles.LineStyle(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, color: str | None = None, color_mode: ColorMode | None = None, width: float | None = None)

The drawing style (color, color mode, and line width) for all line geometry.

Line geometry includes the outlines of outlined polygons and the extruded “tether” of Placemark icons (if extrusion is enabled). https://developers.google.com/kml/documentation/kmlreference#linestyle

class fastkml.styles.PolyStyle(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, color: str | None = None, color_mode: ColorMode | None = None, fill: bool | None = None, outline: bool | None = None)

Drawing style for polygons.

Specifies the drawing style for all polygons, including polygon extrusions (which look like the walls of buildings) and line extrusions (which look like solid fences).

https://developers.google.com/kml/documentation/kmlreference#polystyle

class fastkml.styles.Style(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, styles: Iterable[BalloonStyle | IconStyle | LabelStyle | LineStyle | PolyStyle] | None = None)

A Style defines an addressable style group.

It can be referenced by StyleMaps and Features. Styles affect how Geometry is presented in the 3D viewer and how Features appear in the Places panel of the List view. Shared styles are collected in a <Document> and must have an id defined for them so that they can be referenced by the individual Features that use them.

https://developers.google.com/kml/documentation/kmlreference#style

class fastkml.styles.StyleMap(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, pairs: Iterable[Pair] | None = None)

A <StyleMap> maps between two different Styles. Typically a <StyleMap> element is used to provide separate normal and highlighted styles for a placemark, so that the highlighted version appears when the user mouses over the icon in Google Earth.

https://developers.google.com/kml/documentation/kmlreference#stylemap

class fastkml.styles.StyleUrl(ns: str | None = None, name_spaces: Dict[str, str] | None = None, id: str | None = None, target_id: str | None = None, url: str | None = None)

URL of a <Style> or <StyleMap> defined in a Document.

If the style is in the same file, use a # reference. If the style is defined in an external file, use a full URL along with # referencing.

https://developers.google.com/kml/documentation/kmlreference#styleurl

classmethod get_tag_name() → str

Return the tag name.