Author image Mark Overmeer
and 1 contributors


Geo::KML - produce GoogleEarth KML/KMZ files


   is a XML::Compile::Cache


  *** only run with XML::Compile <= 1.43  The schema's ***
  *** are too messy to parse correctly.                ***

  use Geo::KML;
  my $kml = Geo::KML->new(version => '2.2.0');
  $kml->writeKML($data, $filename);

  my ($ns, $data) = Geo::KML->from('a.kmz');
  defined $ns && $ns eq NS_KML_21
      or die "don't understand file content\n";


  ** You are probably not yet a user of this module.  Don't become
  ** one!  Although KML has an official schema, that is defining
  ** so complex recursive, that parsing usually breaks.  Also, many
  ** KML files do not follow the schema: the order of elements is
  ** strict in the schema, but not in the applications.
  ** Use XML::(Compile::)Simple

KML is the information format for GoogleEarth, an abbreviation of Keyhole Markup Language. Keyhole was the company bought by Google, which had developed the initial version of the GoogleEarth browser. The first version of KML used XML without specs, but version 2 has clean schemas to it. Very complex schemas.

This module is intended to grow with knowledge and features about KML. Please contribute algorithms. It would be nice to have transformations between KML specifications and pleasant abstract objects.

WARNING: in reality, the GoogleEarth application is very forgiving for the message structure, for instance the order of elements and field validation. XML::Compile, the base for this module, is not: it sticks strict to the schema as XML requires. So: reading kml files may not always work, even when the GoogleEarth application accepts it.

WARNING: KML can also be used as layer in GoogleMaps, although that does not support all the features (yet) For maps, the google cloud is used to translate KML into the JSON which the maps browser can handle. See


Methods writeKML() and from() respectively produce and decode KML files. The Perl data structure to be used differs seriously between different KML releases; the KML file is close to the same, however KML 2.2 schemas use a layered type system which will show itself in Perl.

The easiest way to start, is to decode examples first. Go to and look for suitable examples. Then

  use Geo::KML;
  my $data = Geo::KML->from("example.kml");

  use Data::Dumper;
  $Data::Dumper::Indent = 1;
  print Dumper $data;

Also, take a look in the examples directory of this distribution.


 -Option     --Default
  compression  <filename dependent>
  format       <depends>
  version      <required>
compression => 0..9

The compression to be used to write the KMZ ZIP-archives. 9 is best, 0 means uncompressed. The default is 6. See the COMPRESSION_LEVEL_* constants defined by Archive::Zip.

format => 0..2

Output format. A value of '0' means: as compact as possible. When compression is on, then the default is '0' (compact), otherwise '1' (readable).

version => STRING

Which version of KML to read and/or write.


$obj->compression( [BOOLEAN] )

The level of compression (-1, 0..8) for the writer. The optional BOOLEAN changes the setting.

$obj->format( [0..2] )

The output format. With '0', it is optimally compact.


KML version, for instance '2.2.0'.



[release 0.03] Read KML from a source, which can be anything XML::Compile subroutine dataToXML accepts: filename, filehandle, scalar, and more. Returned is a list of two: the type of the KML structure and it parsed content.

You call use ALL options which are provided by XML::Compile::Schema subroutine compile, for instance sloppy_integers and sloppy_floats.

 -Option       --Default
  is_compressed  <auto>
is_compressed => BOOLEAN

When possible, automatically detected from the XMLDATA. However, when the XMLDATA is a file-handle, you may need to set this flag.


  my ($ns, $data) = Geo::KML->from('/tmp/a.kml');
  my ($ns, $data) = Geo::KML->from(\*STDIN, is_compressed => 1);
  if($ns eq NS_KML_220) ...

If ZIPPED is true, or the filename ends with "kmz", a zip archive will get produced. That archive will contain a single doc.kml file. Returned is the MIME-type of the produced data. which is either MIME_KML or MIME_KMZ (when zipped)

You may skip the top-level Document element in the DATA structure.


This module is part of Geo-KML distribution version 0.95, built on August 08, 2014. Website: All modules in this suite: "Geo::Point", "Geo::Proj4", "Geo::WKT", "Math::Polygon", "Geo::GML", "Geo::ISO19139", "Geo::EOP", "Geo::Format::Envisat", and "Geo::Format::Landsat".

Please post questions or ideas to the mailinglist at


Copyrights 2008-2014 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See