> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valar.space/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an AOI
> Define an Area of Interest by drawing on the map, typing coordinates, or pasting GeoJSON
> For the complete documentation index, see [llms.txt](/llms.txt).
Click **New AOI** in the top bar from either the [AOI Overview](/features/areas-of-interest/overview) or [AOI Map](/features/areas-of-interest/map) page to start creating an AOI. The button always lands you on the AOI Map first, then opens a method picker so you choose how to define the geometry: by drawing on the map, by typing coordinates into a form, or by pasting a GeoJSON document. **Save** persists the AOI; an automatic recompute fires once you save so the events forecast populates immediately.
**Route:** Opened from the **New AOI** button on the [AOI Overview](/features/areas-of-interest/overview) page or the [AOI Map](/features/areas-of-interest/map) page. Clicking the button from either page navigates to `/aoi/map` first and then opens the method picker.
## Method Picker
The picker is a modal headed **Create a new AOI** with the subtitle *Pick how you want to define the area of interest.* It offers three cards — none is preselected:
| Card | When to use |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Draw on map** | Sketch the AOI directly on the map. Use this when you have a visual reference and want to define the shape interactively. |
| **Coordinate form** | Type latitude / longitude coordinates by hand. Use this when you have precise vertices in mind, or when you are converting from another system. |
| **GeoJSON** | Paste or upload a GeoJSON file. Use this when you already have a GeoJSON document from QGIS, ArcGIS, or another GIS tool. |
Click a card to pick the method; the picker closes and the corresponding creation surface opens. Click **Cancel**, click outside the modal, or press **Escape** to dismiss the picker without choosing.
## Draw on Map
Picking **Draw on map** keeps you on the AOI Map and surfaces a floating toolbar in the top-left corner of the canvas.
The toolbar segments are:
| Segment | Behaviour |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Polygon** | Click each vertex on the map; double-click or click the first vertex to close the shape. |
| **Rectangle** | Click and release for the first corner, then click and release for the opposite corner. |
| **Disk** | Click the centre, drag to the desired radius, and release. The radius is computed as the great-circle distance from the centre to the furthest sketched point. |
A helper text reading `Draw a shape on the map to continue` renders beneath the toolbar until the shape is complete.
Once you finish the shape, a small popover anchors at the top-right corner of the map with the AOI form (described below). The shape stays visible on the map and updates live when you adjust fields.
## Coordinate Form
Picking **Coordinate form** opens the AOI form in a centered modal dialog headed **New AOI — Coordinate form**. As you type vertices, a dashed sky-blue preview of the shape renders on the world map behind the dialog so you can sanity-check the geometry against the basemap.
The geometry editor at the top of the form lets you pick the primitive (Polygon, Disk, or Multipolygon) and enter the structured fields:
| Primitive | Inputs |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Polygon** | A list of vertices, each a latitude (`-90..90`) and longitude (`-180..180`) pair. **Add vertex** extends the list. |
| **Disk** | Centre latitude, centre longitude, and a radius (in kilometres in the form; the wire format uses metres internally). |
| **Multipolygon** | Two or more piece blocks, each a polygon vertex list. **Add piece** extends the list. |
A polygon with fewer than 3 vertices surfaces `Add at least 3 vertices to continue` and disables **Save** until the geometry is valid. The form caps each polygon at 100 vertices.
## GeoJSON
Picking **GeoJSON** opens the AOI form in a centered modal dialog headed **New AOI — GeoJSON**. A textarea + file picker at the top accepts your GeoJSON; the live preview on the map behind the dialog updates as soon as the document parses.
| Control | Behaviour |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GeoJSON textarea** | Paste any GeoJSON document. The placeholder reads *Paste a Polygon / Disk / MultiPolygon GeoJSON Feature here…*. Live preview updates on every keystroke. |
| **Upload .geojson file** | Opens the file picker. Accepts `.geojson` and `application/geo+json` content. Files larger than 1 MB are rejected before being read; the textarea is not populated. |
While the textarea is empty, a helper line reads `Paste valid GeoJSON to continue`. While a parse fails, the helper reads `GeoJSON must be a Polygon, Disk, or MultiPolygon`. While a file is too large, the helper reads `GeoJSON file must be 1 MB or smaller`. See the [GeoJSON file format](/file-formats/aoi-geojson) page for the supported RFC 7946 subset.
## Shared Form Fields
Regardless of the creation method, every AOI form surfaces the same sections beneath the geometry block.
### Identity
| Field | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name** | Required. Up to 100 characters. Must be unique within the workspace. |
| **Description** | Optional. Up to 100 characters with a live counter beneath the field. |
| **Tags** | Optional. Up to 20 chips, each ≤64 characters. Press **Enter** or `,` to commit a chip; press **Backspace** on an empty input to remove the last chip. |
| **Color** | A 12-swatch palette: Emerald, Teal, Sky, Blue, Indigo, Violet, Fuchsia, Rose, Red, Orange, Amber, Lime. Defaults to **Emerald**. |
### Lifecycle
| Field | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| **Active** | Default on. When off, the AOI generates no overflight events even if it has a populated schedule. |
| **Validity start (UTC)** | Optional. When set, also requires **Validity end (UTC)**. |
| **Validity end (UTC)** | Optional. When set, also requires **Validity start (UTC)**. Must be strictly after the start. |
The create form is paired — leave both bounds empty for an always-active AOI, or set both together. To produce a one-bound (open-ended) window, create the AOI without bounds, then edit it via the dialog on the [AOI Overview](/features/areas-of-interest/overview) page, which exposes a per-bound **Set / Open-ended** switch.
All times are UTC.
## Validation Errors
The form validates input inline before letting you **Save**. The error strings are surfaced verbatim:
| Error | What triggered it |
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `Name is required` | The Name field is blank or contains only whitespace. |
| `Both validity dates required, or neither` | Only one of the validity bounds is filled in. |
| `Validity end must be after validity start` | Both validity bounds are set and the end is at or before the start. |
| `Up to 20 tags, each ≤64 characters` | Either the tag count exceeds 20 or a single tag exceeds 64 characters. |
| `Add at least 3 vertices to continue` | The Coordinate-form polygon has fewer than 3 vertices. |
| `GeoJSON must be a Polygon, Disk, or MultiPolygon` | The pasted or uploaded GeoJSON could not be parsed as a supported AOI primitive. |
| `GeoJSON file must be 1 MB or smaller` | The uploaded `.geojson` file exceeds 1 MB. |
| `Polygon edges must not intersect` | The polygon has self-intersecting edges. |
| `Polygon must have at least 3 distinct vertices` | The polygon has fewer than 3 distinct vertices after submission. |
| `Polygon must have at most 500 distinct vertices` | The polygon exceeds the 500-vertex backend cap (the Coordinate form caps at 100). |
| `Polygon must have positive area` | The polygon is degenerate (zero area). |
| `Polygon must not span more than a hemisphere` | The polygon extent is too large for the spherical model. |
| `MultiPolygon must have at least 2 disjoint pieces` | A multipolygon needs at least 2 pieces; use a single polygon for one piece. |
| `MultiPolygon must have at most 50 disjoint pieces` | The multipolygon exceeds the 50-piece cap. |
| `MultiPolygon pieces must have disjoint interiors` | Two or more multipolygon pieces overlap. |
| `Disk radius must be greater than 0 m and at most 500,000 m` | The disk radius is outside the accepted range. |
| `Latitude must be between -90° and 90°` | A latitude input is outside `[-90, 90]`. |
| `Longitude must be between -180° and 180°` | A longitude input is outside `[-180, 180]`. |
| `Could not parse this file as GeoJSON. Please check the format.` | The GeoJSON body is malformed or unparseable. |
| `This primitive is not supported. Supported primitives: Polygon, CircularDisk, MultiPolygon.` | The GeoJSON references a primitive outside the supported subset. |
| `Polygons with holes are not supported` | The polygon has interior rings (holes). |
| `GeometryCollection is not supported` | The GeoJSON uses a GeometryCollection wrapper. |
| `FeatureCollection with multiple features is not supported` | The FeatureCollection contains more than one feature. |
| `Point and MultiPoint are not supported` | The GeoJSON uses Point or MultiPoint geometries. |
| `File exceeds 1 MB limit (1,000,000 bytes). Simplify in QGIS/ArcGIS before paste.` | The pasted or uploaded GeoJSON body exceeds 1 MB on the server. |
| `An AOI with this name already exists in this workspace.` | An AOI with the same name already exists in the workspace. |
| `End date must be after start date.` | The validity window's end is at or before the start. |
| `Provide either structured geometry or GeoJSON, not both` | Both a structured geometry block and a GeoJSON body were submitted. |
## Saving and Cancelling
Click **Save** to create the AOI. The button reads **Saving…** while the request is in flight. On success the form closes, the new AOI is selected on the map, and an automatic recompute fires so the events forecast populates immediately. If the save rejects, an inline banner above the form reads `Couldn't save AOI — try again`; the banner clears the moment you edit any field.
Click **Cancel** to discard the draft. If you have unsaved changes, a confirmation dialog **Discard changes** appears with the body `Discard your changes? Your edits will be lost.` Choose **Keep editing** to return to the form or **Discard** to close it. A non-dirty cancel routes straight to the closing transition.
## Editing an Existing AOI
To edit an existing AOI, open the [AOI Overview](/features/areas-of-interest/overview) page, select the AOI, and click the pen icon in the identity hero to enter edit mode. Identity fields become inline-editable; the validity window opens an edit dialog from the geometry block. The full editing workflow — including the kebab actions for **Set active**, **Set inactive**, and **Delete AOI** — is documented on the Overview page.
Editing the geometry, the validity window, or the **Active** flag automatically triggers a recompute. Editing only identity fields (name, description, tags, colour) does not trigger a recompute; existing events stay in the list.
## Deleting an AOI
Deletion is initiated from the kebab menu in the identity hero on the [AOI Overview](/features/areas-of-interest/overview) page, or from the kebab menu on a hovercard on the [AOI Map](/features/areas-of-interest/map) page. Both paths surface a **Delete AOI** confirmation dialog; click **Delete** to confirm or **Cancel** to keep the AOI. After deletion the page navigates to the next remaining AOI, or to the empty state if it was the only one.
## Related Pages
* [Areas of Interest overview](/features/areas-of-interest/overview) — read and edit an existing AOI in depth.
* [AOI Map](/features/areas-of-interest/map) — the world map where every creation flow begins.
* [Overflight events](/features/areas-of-interest/overflight-events) — the 7-day forecast that follows every AOI save.
* [GeoJSON file format](/file-formats/aoi-geojson) — the supported RFC 7946 subset accepted by the **GeoJSON** flow.