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, **kwargs: Any)

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, **kwargs: Any)

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: ModuleType) → None

Set the etree implementation to use.

Geometry

class fastkml.geometry.Coordinates(*, ns: str | None = None, name_spaces: Dict[str, str] | None = None, coords: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | None = None, **kwargs: Any)

Represents a set of coordinates in decimal degrees.

Attributes

coords (LineType): A list of tuples representing the coordinates.

Each coord consists of floating point values for longitude, latitude, and altitude. The altitude component is optional. Coordinates are expressed in decimal degrees only.

classmethod get_tag_name() → str

Return the tag name.

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 | None = None, kml_coordinates: Coordinates | None = None, **kwargs: Any)

Defines a connected set of line segments.

Use <LineStyle> to specify the color, color mode, and width of the line. When a LineString is extruded, the line is extended to the ground, forming a polygon that looks somewhat like a wall or fence. For extruded LineStrings, the line itself uses the current LineStyle, and the extrusion uses the current PolyStyle. See the KML Tutorial for examples of LineStrings (or paths).

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

property geometry: LineString | None

Get the LineString geometry.

Returns

Optional[geo.LineString]: The LineString geometry, or None if it doesn’t exist.

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 | None = None, kml_coordinates: Coordinates | None = None, **kwargs: Any)

Defines a closed line string, typically the outer boundary of a Polygon.

Optionally, a LinearRing can also be used as the inner boundary of a Polygon to create holes in the Polygon. A Polygon can contain multiple <LinearRing> elements used as inner boundaries.

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

property geometry: LinearRing | None

Get the geometry of the LinearRing.

Returns

Optional[geo.LinearRing]: The geometry of the LinearRing, or None if kml_coordinates is not set or if there is a DimensionError.

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, kml_geometries: Iterable[Point | LineString | Polygon | LinearRing | Self] | None = None, geometry: MultiPoint | MultiLineString | MultiPolygon | GeometryCollection | None = None, **kwargs: Any)

A container for zero or more geometry primitives associated with the same feature.

property geometry: MultiPoint | MultiLineString | MultiPolygon | GeometryCollection | None

Returns the geometry of the MultiGeometry.

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 | None = None, kml_coordinates: Coordinates | None = None, **kwargs: Any)

A geographic location defined by longitude, latitude, and (optional) altitude.

When a Point is contained by a Placemark, the point itself determines the position of the Placemark’s name and icon. When a Point is extruded, it is connected to the ground with a line. This “tether” uses the current LineStyle.

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

property geometry: Point | None

Get the geometry object of the Point.

Returns

Optional[geo.Point]: The geometry object of the Point, or None if it doesn’t exist.

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, outer_boundary_is: OuterBoundaryIs | None = None, inner_boundary_is: InnerBoundaryIs | None = None, geometry: Polygon | None = None, **kwargs: Any)

A Polygon is defined by an outer boundary and 0 or more inner boundaries.

The boundaries, in turn, are defined by LinearRings. When a Polygon is extruded, its boundaries are connected to the ground to form additional polygons, which gives the appearance of a building or a box. Extruded Polygons use <PolyStyle> for their color, color mode, and fill.

The <coordinates> for polygons must be specified in counterclockwise order.

The outer boundary is represented by the outer_boundary_is attribute, which is an instance of the OuterBoundaryIs class. The inner boundaries are represented by the inner_boundary_is attribute, which is an instance of the InnerBoundaryIs class.

The geometry property returns a geo.Polygon object representing the geometry of the Polygon.

Example usage: ` polygon = Polygon(outer_boundary_is=outer_boundary, inner_boundary_is=inner_boundary) print(polygon.geometry) `

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

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, **kwargs: Any)
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, **kwargs: Any)

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, **kwargs: Any)

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) → Self

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 etree 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, **kwargs: Any)

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, **kwargs: Any)

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, **kwargs: Any)

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, **kwargs: Any)

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, **kwargs: Any)

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, **kwargs: Any)

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, **kwargs: Any)

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, **kwargs: Any)

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.