KML - Keyhole Markup Language

Keyhole Markup Language (KML) is an XML-based language for managing the display of 3D geospatial data. KML has been submitted as an OGC standard candidate as of this writing, and is supported in one way or another on the major GeoBrowsers. Note that KML by specification uses only a single projection, EPSG:4326. All OGR KML output will be presented in EPSG:4326.

At this time, only vector layers are output by the KML driver. There are additional scripts supplied with the GDAL project that can build other kinds of output.

KML Writing

The OGR KML driver has implemented basic support for writing KML. Since not all features of KML are able to be represented in the internal OGR model, you will not be able to generate many KML-specific attributes from within GDAL/OGR. Please try a few test files to get a sense of what is possible.

KML Reading

KML reading has been added to OGR v1.5. To enable KML reading, you must have the XML Parser Expat v2.0 or greater installed on your system, and OGR must be built with the configure flag --with-expat.

KML reading is also subject to the limitations of the internal GDAL/OGR model. For example, nested folders in a source KML file are disregarded, and folder xxdescriptionxx tags will not carry through to ouput.

Creation Issues

When outputting KML, the OGR KML driver will translate an OGR Layer into a KML Folder. Although KML and a few other OGR formats allow mixing the geometry types of Layer Elements, generally OGR prefers to keep one kind of geometry in a Layer. You may encounter unexpected behavior if you try to mix the geometry types of elements in a layer, for example, LINESTRING and POINT data.

The KML Driver will rename some layers, or source KML folder names, into new names it considers valid, for example 'Layer #0', the default name of the first unnamed Layer, becomes Layer__0.

KML is mix of formatting and feature data. The xxdescriptionxx tag of a Placemark will be displayed in most geobrowsers as an HTML-filled balloon. When writing KML, Layer element attributes are added as description tag content with the following HTML structure:

Attribute name: Attribute content

Limited support is available for fills, line color and other styling attributes. Please try a few sample files to get a better sense of actual behavior.

Creation Options

The following creation options are supported:

NameField: Allows you to specify the field to use for the KML <name> element. Default value : 'Name'

name field example??

DescriptionField: Allows you to specify the field to use for the KML <name> element. Default value : 'Description'

ogr2ogr -f KML output.kml input.shp -dsco NameField=RegionName

AltitudeMode: Allows you to specify the AltitudeMode to use for KML geometries. This will only affect 3D geometries and must be one of the valid KML options. See the relevant KML reference material for further information.
```
ogr2ogr -f KML output.kml input.shp -dsco AltitudeMode=absolute
```

Example

The ogr2ogr utility can be used to dump the results of a PostGIS query to KML:

ogr2ogr -f KML output.kml PG:'host=myserver dbname=warmerda' -sql "SELECT pop_1994 from canada where province_name = 'Alberta'"

Caveats

The Google Earth seems to have some limits regarding the number of coordinates in complex geometries like polygons. If the problem appears, then problematic geometries are displayed completely or partially covered by vertical stripes. Unfortunately, there are no exact number given in the KML specification about this limitation, so the KML driver will not warn about potential problems. One of possible and tested solutions is to simplify a line or a polygon to remove some coordinates. Here is the whole discussion about this issue on the Google KML Developer Forum, in the polygon displays with vertical stripes thread.