---
title: "Choose the minimal set of captures whose clear ground covers the AOI within one temporal epoch. Returns coverage, the true date span, and what is left uncovered. Buys nothing."
method: POST
path: "/v1/catalog/clear_coverage/plan"
tags: ["resource-facade"]
---

# Choose the minimal set of captures whose clear ground covers the AOI within one temporal epoch. Returns coverage, the true date span, and what is left uncovered. Buys nothing.

`POST /v1/catalog/clear_coverage/plan`

## Headers

- `x-api-key` string, nullable

## Request body

- ClearCoverageInput
  - `aoi` object, required — GeoJSON Polygon of the area of interest
  - `scenes` SrcOperationsCatalogClearCoverageSceneRef[], required
    - `scene_id` string, required
    - `footprint` object, required — GeoJSON Polygon of the scene
    - `thumbnail_url` string, required
    - `captured_at` string, nullable
    - `off_nadir_deg` number, nullable
    - `sun_elevation_deg` number, nullable
    - `vendor_cloud_pct` number, nullable
    - `sensor` string, nullable
    - `vendor` string, nullable
  - `target_coverage` number — Stop once this fraction of the AOI is covered by clear ground.
  - `max_span_days` integer — Hard limit on the date range of a composite. A stack spanning months is not a single-date image; sun angle, shadow length and vegetation all differ. Set 0 to forbid compositing entirely.
  - `max_scenes` integer
  - `target_date` string, nullable — ISO date to prefer captures near, e.g. 2026-03-15
  - `date_priority` string — How hard to pull toward target_date. 'off' ignores it; 'balanced' lets it break ties and order a series without buying a worse capture; 'strict' outweighs even a billing step, for work where the date matters more than the price.
  - `max_off_nadir_deg` number, nullable
  - `min_sun_elevation_deg` number, nullable
  - `vendors` string[], nullable — e.g. ["CGSTL"] to order Jilin only
  - `min_marginal_gain` number — Smallest share of the AOI a capture must add to be worth taking, when taking it does NOT push the order into a higher billing multiplier.
  - `allow_billing_step` boolean — Whether a capture may push the order into a higher billing multiplier at all. False caps the order at its current multiplier.
  - `billing_step_min_gain` number — How much a capture must add before it is allowed to cross a billing threshold. Guards against buying 2% more ground for twice the price.

## Response `200`

Successful Response

- PlanOutput
  - `coverage` number, required
  - `complete` boolean, required
  - `is_composite` boolean, required
  - `span_days` integer, required
  - `members` object[], required
  - `uncovered` object, nullable
  - `needs_review` boolean
  - `review_reason` string, nullable
  - `scenes` SceneCoverage[]
    - `scene_id` string, required
    - `clear_fraction` number, required
    - `aoi_obscured_fraction` number
    - `scene_obscured_fraction` number
    - `thick_fraction` number, required
    - `thin_fraction` number, required
    - `shadow_fraction` number, required
    - `vendor_cloud_pct` number, nullable
    - `vendor_disagrees` boolean
    - `geometry_ok` boolean
    - `reason` string, nullable
    - `cloud` object, nullable
    - `shadow` object, nullable
  - `coverage_ratio` number
  - `billed_multiplier` integer
  - `free_budget_remaining` number
  - `aoi_geometry_invalid` boolean
  - `excluded_by_filter` object

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.dev/geopera/apis/geopera-data-platform.md) · [All operations](https://skmtc.dev/geopera/apis/geopera-data-platform/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/geopera/geopera-data-platform/revisions/cb0130b2a40a/schema)