KML and KMZ Files

For the complete documentation index, see llms.txt.

When you create an Area of Interest with the KML method (see the KML upload in the AOI creation dialog), VALAR reads a single area out of a .kml or .kmz file and converts it to the same typed geometry the GeoJSON flow produces. This page catalogues what geometry is accepted, what is silently dropped, the file-size limits, and what each import error means.

KML is an OGC standard originally created for Google Earth. A .kmz file is a ZIP archive containing a KML document — it is the default format Google Earth exports.

Supported Geometry

VALAR imports exactly one area per file. That area is either a single polygon or a set of polygons:

KML geometry	Result
Polygon	A single `<Polygon>` in one `<Placemark>` becomes a Polygon AOI. Exterior ring only.
MultiGeometry of Polygons	A `<MultiGeometry>` whose members are all `<Polygon>` becomes a MultiPolygon AOI (one AOI made of several disjoint pieces).

The imported polygons follow the same vertex and area rules the GeoJSON subset enforces — an exterior ring of 3 to 500 distinct vertices per piece, positive area, no self-intersection, and at most a hemisphere of extent. See the Validation Errors catalogue for the full list.

Rejected Geometry

Anything that is not a single polygonal area is rejected before the area reaches the map:

Input	Why it is rejected
Point or LineString	AOIs are areas — a point or a line has no area to import.
A MultiGeometry mixing polygons with non-polygons	Only all-polygon geometries convert to an AOI.
Multiple placemarks / multiple areas	One area per file. Split a multi-area file and import each area separately.

What Is Dropped on Import

VALAR keeps only the area outline. The following are dropped without failing the import:

Dropped	Behaviour
Holes (inner rings)	A polygon with a hole is accepted; only its outer ring is kept. The hole is silently discarded.
Altitude (3rd coordinate)	If a coordinate carries a `,altitude` value, it is dropped. AOIs are 2D Earth-surface regions.
Name and styling	The KML file’s own placemark name, description, colour, and style are ignored. You name and colour the AOI in the creation form.

File Types and Size Limits

Constraint	Limit
Accepted extensions	`.kml` (plain KML) and `.kmz` (zipped KML — the Google Earth default export).
Maximum `.kmz` file size	5 MB compressed. Larger archives are rejected before being read.
Maximum extracted KML size	1 MB of KML text (the same cap as a pasted or uploaded GeoJSON body). This bound is enforced while the `.kmz` is unzipped, so a small archive that expands to a huge document is still rejected.

Import Errors

Each failure surfaces a single inline message on the KML card. No area is placed on the map until the file passes every check.

Message	Cause	Remediation
`The file could not be read as KML`	The file is not valid KML, or carries an XML `DOCTYPE` declaration.	Re-export the area as plain KML from your GIS tool.
`The KML area must be a Polygon or set of Polygons`	The file’s geometry is a point, a line, or a mix that is not all polygons.	Export the area as a polygon (or a set of polygons).
`This KML file contains multiple areas — import a single area`	The file has more than one placemark / area.	Keep one area per file and import each separately.
`No supported area (Polygon) was found in the KML`	The file (or `.kmz` archive) has no importable polygon inside.	Check that the file actually contains a polygon area.
`The KML or KMZ file is too large to import`	The `.kmz` exceeds 5 MB, or the KML text exceeds 1 MB.	Simplify the geometry in a desktop GIS tool, then re-export.
`This KML/KMZ file is encrypted and cannot be read`	The `.kmz` archive is password-protected.	Re-export an unencrypted `.kml` or `.kmz`.

Worked Example

Below is a valid KML file describing a small AOI over the Tuscany coast near Livorno — one placemark, one polygon, a closed outer ring, no hole, no altitude.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Placemark>
    <name>Tuscany Coast</name>
    <Polygon>
      <outerBoundaryIs>
        <LinearRing>
          <coordinates>
            10.20,43.80 10.40,43.80 10.40,43.60 10.20,43.60 10.20,43.80
          </coordinates>
        </LinearRing>
      </outerBoundaryIs>
    </Polygon>
  </Placemark>
</kml>

Save this as tuscany.kml, pick KML in the AOI creation dialog, upload the file, fill in the rest of the Create an AOI form, and Save — the AOI lands in the workspace and an automatic recompute follows. To try the .kmz path, zip the same file (Google Earth’s Save Place As… → .kmz does this for you) and upload the archive instead.

Create an AOI — the creation dialog where the KML method lives.
GeoJSON file format — the sibling import format; KML areas convert to the same accepted geometry.
Areas of Interest overview — read and edit an AOI once it is imported.

Core Concepts

File Formats

Supported Geometry

Rejected Geometry

What Is Dropped on Import

File Types and Size Limits

Import Errors

Worked Example

​Supported Geometry

​Rejected Geometry

​What Is Dropped on Import

​File Types and Size Limits

​Import Errors

​Worked Example

​Related Pages

Supported Geometry

Rejected Geometry

What Is Dropped on Import

File Types and Size Limits

Import Errors

Worked Example

Related Pages