KML and KMZ Files

For the complete documentation index, see llms.txt.

VALAR reads a single area out of a .kml or .kmz file and converts it to the same typed geometry the GeoJSON flow produces. You supply that file in one of two places: when you create an Area of Interest with the KML method (see the KML upload in the AOI creation dialog), or when you replace the boundary of an area you already track (see Replace the boundary from a file). This page catalogues what geometry is accepted, what is silently dropped, the file-size limits, and what each error means — all of it identical on both paths. The page covers both directions. Everything up to Exporting a Boundary is the import contract — the KML VALAR accepts from you. That final section is the export contract — the KML VALAR produces from an area you already track. The two are deliberately different, and the export section says where and why.

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. Its `<outerBoundaryIs>` ring only — a polygon that also carries an `<innerBoundaryIs>` ring is rejected, not trimmed.
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 solid 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.
A polygon with a hole (`<innerBoundaryIs>`)	An AOI is a solid area with no cut-outs. Importing only the outer ring would cover ground you deliberately excluded, so the file is refused instead.

What Is Dropped on Import

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

Dropped	Behaviour
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.

Replacing an Existing Boundary

An area’s boundary can be replaced from a file long after the area was created, from the Replace from file… control in the geometry editor on the Areas of Interest overview page. The file is read exactly as it is on the creation path:

Rule	On the replace path
Supported geometry	Every shape in Supported Geometry is accepted identically — a single `<Polygon>`, or a `<MultiGeometry>` whose members are all `<Polygon>`.
Rejected geometry	Everything in Rejected Geometry is refused identically — points, lines, mixed multi-geometries, multiple areas, and polygons carrying an `<innerBoundaryIs>` hole.
What is dropped	Altitude values, placemark names, and styling are dropped the same way. The area keeps the name, description, tags, and colour it already has.
File size	Unchanged: 5 MB compressed for a `.kmz`, and 1 MB of extracted KML text.

A file holding more than one area is refused on both paths with the same message — This KML file contains multiple areas — import a single area. Split the file and supply a single area, whether you are creating the AOI or replacing its boundary. The replace dialog also accepts a .geojson file; see the GeoJSON file format page for that subset.

Import Errors

Each failure surfaces a single inline message — on the KML card when you are creating an area, and inside the replace dialog when you are replacing a boundary. No area is placed on the map until the file passes every check, and a refused replacement leaves the existing boundary untouched.

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).
`Polygons with holes are not supported`	A polygon in the file carries an `<innerBoundaryIs>` ring.	Remove the inner ring, or split the area into solid pieces that leave the hole out, then re-export.
`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. The same file also drives the replace path: open an existing area in edit mode, click Replace from file…, and choose it.

Exporting a Boundary

Everything above is the import contract — what VALAR accepts from you. This section is the export contract — what VALAR produces from an area you already track. Export runs from the area’s own actions menu on the Areas of Interest overview page: choose Export as KML and the file downloads directly. It is named aoi-<area-name>-<yyyymmdd>.kml, where the date is the UTC calendar date of the export. Export writes plain .kml only — there is no .kmz export, though both extensions are accepted on import.

What the File Contains

One <Document> holding one <Placemark>, whatever the area’s shape:

Element	Content
`<name>`	The area’s name, on both the `<Document>` and the `<Placemark>`.
`<description>`	A fixed caveat, quoted below, so the limits travel with the file into whatever opens it.
`<ExtendedData>`	The area’s description, its tags as a comma-separated list, and the six provenance values described below.
Geometry	A single `<Polygon>` for a single-piece area, or one `<MultiGeometry>` of `<Polygon>` elements for a multi-piece one. A multi-piece area is still one Placemark, so it stays one selectable feature.
`<outerBoundaryIs>`	The exterior ring only. No `<innerBoundaryIs>` is ever written — holes are not represented.
`<coordinates>`	Space-separated `longitude,latitude` pairs in decimal degrees, WGS 84, rounded to 6 decimal places. No altitude component. Every ring is closed and wound counter-clockwise.
`<altitudeMode>`	`clampToGround`, with `<tessellate>1</tessellate>`, so the boundary drapes over terrain instead of cutting through it.

No <Style> is written — the consumer owns presentation. Nothing beyond the fields above leaves the product: never the area’s validity window, colour, active flag, computed overflight events, or any workspace identifier. Every exported file carries this <description> verbatim:

This file contains the area boundary only, not its overflight results. The boundary is exported as straight segments; the file’s maxDeviationM value states how far they depart from the stored outline. VALAR’s published bound is 250 m for latitudes up to 89.5°.

Accuracy of the Exported Boundary

VALAR computes overflights against a boundary whose edges are great-circle arcs. A KML <LinearRing> has no arc primitive, so every edge in the file is a straight segment, and each one is subdivided until it tracks the arc closely.

Exported area boundaries are densified so that every edge stays within 250 m on the ground of the great-circle boundary VALAR computes overflights against. This is a geometric bound only. It does not guarantee that a third-party tool re-evaluating access against the exported boundary reproduces VALAR’s overflight results: whether a boundary deviation changes an access determination depends on the tasked sensor’s footprint and slew geometry, which is not known when the area is exported.

The 250 m bound holds for absolute latitude up to 89.5°.

The `valar` Provenance Block

KML has no nested-object type, so the provenance block is flattened into <ExtendedData> as six <Data name="valar.…"> entries. It carries exactly six values, in this order:

`<Data name>`	Example	Meaning
`valar.producer`	`VALAR`	The system that wrote the file.
`valar.schemaVersion`	`1.0`	Version of the file layout. It changes only when the structure changes in a way a consumer must react to.
`valar.generatedAt`	`2026-07-22T14:03:11.482Z`	The instant the file was written, ISO 8601, UTC.
`valar.boundaryOnly`	`true`	Always `true`. States that the file carries the boundary and nothing else — no overflight events and no forecast.
`valar.maxDeviationM`	`4.9`	The largest distance, in metres, between any segment written to the file and the great-circle edge it approximates. Measured from the segments in this specific file — it is not a fixed constant and not the 250 m bound, though it is always at or below that bound.
`valar.deviationModel`	`great-circle-chord-sagitta`	Names the quantity `valar.maxDeviationM` measures, so a consumer does not have to infer it.

valar.boundaryOnly sits immediately before valar.maxDeviationM deliberately: the accuracy figure describes the boundary, and the file carries no overflight results for it to describe.

In OGC KML 2.2 a <Data name> element’s <value> is a string — the format has no typed values. A consumer must parse every value in <ExtendedData> as a string. The number and boolean types used on the GeoJSON side do not survive into KML: maxDeviationM arrives as the string "4.9", not a number, and boundaryOnly arrives as the string "true", not a boolean. Compare it as text, or convert it before use.

An Exported File Is Not an Import File

A file VALAR exports is not guaranteed to import back into VALAR, and usually will not. The two contracts are deliberately asymmetric, in both directions:

Asymmetry	Why the two differ
Export writes more than import accepts	Densification adds positions. An exported ring routinely carries far more than the 500 distinct vertices per ring the import route accepts, so re-importing it is refused on vertex count. No vertex ceiling is applied on export, because truncating the ring would emit a boundary that is not the one VALAR holds.
Import accepts more than export writes	A circular area, an area crossing the 180° meridian, and an area enclosing a pole can each be created in VALAR, but none of them can be exported. See Export a boundary for the refusal reasons.

Export exists to hand a boundary to another tool — Google Earth, a GIS package, a planning system, your own pipeline — not to move areas between VALAR workspaces. To change an area’s boundary inside VALAR, use Replace from file… on the Areas of Interest overview page.

Worked Example — An Exported File

A small, mid-latitude polygon area exports to a document like this:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>Tuscany Coast</name>
    <Placemark>
      <name>Tuscany Coast</name>
      <description>This file contains the area boundary only, not its overflight results. The boundary is exported as straight segments; the file&apos;s maxDeviationM value states how far they depart from the stored outline. VALAR&apos;s published bound is 250 m for latitudes up to 89.5°.</description>
      <ExtendedData>
        <Data name="description">
          <value></value>
        </Data>
        <Data name="tags">
          <value></value>
        </Data>
        <Data name="valar.producer">
          <value>VALAR</value>
        </Data>
        <Data name="valar.schemaVersion">
          <value>1.0</value>
        </Data>
        <Data name="valar.generatedAt">
          <value>2026-07-22T14:03:11.482Z</value>
        </Data>
        <Data name="valar.boundaryOnly">
          <value>true</value>
        </Data>
        <Data name="valar.maxDeviationM">
          <value>4.9</value>
        </Data>
        <Data name="valar.deviationModel">
          <value>great-circle-chord-sagitta</value>
        </Data>
      </ExtendedData>
      <Polygon>
        <altitudeMode>clampToGround</altitudeMode>
        <tessellate>1</tessellate>
        <outerBoundaryIs>
          <LinearRing>
            <coordinates>10.2,43.6 10.4,43.6 10.4,43.8 10.2,43.8 10.2,43.6</coordinates>
          </LinearRing>
        </outerBoundaryIs>
      </Polygon>
    </Placemark>
  </Document>
</kml>

This area’s edges are short enough, and far enough from the poles, that none of them needed subdividing — so the exported ring holds the same positions the area was created with. A wider area, or one nearer a pole, carries many more positions than it was created with, and a correspondingly different valar.maxDeviationM.

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, and replace its boundary from a file.

Core Concepts

File Formats

Supported Geometry

Rejected Geometry

What Is Dropped on Import

File Types and Size Limits

Replacing an Existing Boundary

Import Errors

Worked Example

Exporting a Boundary

What the File Contains

Accuracy of the Exported Boundary

The `valar` Provenance Block

An Exported File Is Not an Import File

Worked Example — An Exported File

​Supported Geometry

​Rejected Geometry

​What Is Dropped on Import

​File Types and Size Limits

​Replacing an Existing Boundary

​Import Errors

​Worked Example

​Exporting a Boundary

​What the File Contains

​Accuracy of the Exported Boundary

​The valar Provenance Block

​An Exported File Is Not an Import File

​Worked Example — An Exported File

​Related Pages

Supported Geometry

Rejected Geometry

What Is Dropped on Import

File Types and Size Limits

Replacing an Existing Boundary

Import Errors

Worked Example

Exporting a Boundary

What the File Contains

Accuracy of the Exported Boundary

The `valar` Provenance Block

An Exported File Is Not an Import File

Worked Example — An Exported File

Related Pages