---
title: "Measure AOI coverage for candidate scene footprints: per-scene overlap and marginal gain vs a selection, coverage roll-ups with gap geometry, and an optional greedy pick."
method: POST
path: "/v1/op/catalog.scene_coverage"
tags: ["kernel-ops"]
---

# Measure AOI coverage for candidate scene footprints: per-scene overlap and marginal gain vs a selection, coverage roll-ups with gap geometry, and an optional greedy pick.

`POST /v1/op/catalog.scene_coverage`

## Headers

- `x-api-key` string, nullable

## Request body

- SceneCoverageInput
  - `aoi` object, required — Target area GeoJSON Polygon or MultiPolygon
  - `scenes` SceneCandidate[], required
    - `id` string, required
    - `geometry` object, required — Scene footprint GeoJSON (Polygon/MultiPolygon)
    - `cloud_cover` number, nullable — Cloud cover percent (STAC properties.cloudCoverage / eo:cloud_cover)
  - `selected_ids` string[] — Scene ids already selected; metrics are marginal to these
  - `max_cloud_pct` number, nullable — Cloud ceiling. Scenes above it (or with unknown cloud) are measured but excluded from cloud-free roll-ups and from the greedy suggestion.
  - `suggest` boolean — Also return a greedy pick maximising marginal coverage
  - `max_scenes` integer — Greedy suggestion size ceiling
  - `target_coverage_pct` number — Greedy stops once selection+suggestion reaches this

## Response `200`

Successful Response

- SceneCoverageOutput
  - `aoi_area_sq_km` number
  - `selected` CoverageSummary, required
    - `scene_count` integer
    - `coverage_sq_km` number
    - `coverage_pct` number
    - `cloudfree_coverage_pct` number
    - `gap_geometry` object, nullable
  - `best_possible` CoverageSummary, required
    - `scene_count` integer
    - `coverage_sq_km` number
    - `coverage_pct` number
    - `cloudfree_coverage_pct` number
    - `gap_geometry` object, nullable
  - `candidates` CandidateMetric[]
    - `id` string, required
    - `cloud_cover` number, nullable
    - `aoi_overlap_sq_km` number — scene ∩ AOI, km² (never double-counted)
    - `aoi_overlap_pct` number — scene ∩ AOI as % of the AOI
    - `incremental_sq_km` number — NEW AOI area this scene adds beyond selected_ids
    - `incremental_pct` number
    - `redundant_pct` number — % of this scene's AOI-overlap already covered by selected_ids
  - `suggestion` CoverageSuggestion
    - `ids` string[]
    - `coverage` CoverageSummary, required
      - `scene_count` integer
      - `coverage_sq_km` number
      - `coverage_pct` number
      - `cloudfree_coverage_pct` number
      - `gap_geometry` object, nullable
    - `steps` SuggestionStep[]
      - `id` string, required
      - `added_sq_km` number, required
      - `cumulative_pct` number, required
    - `target_reached` boolean

## 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)