---
title: "Count vessels in a SAR scene"
method: POST
path: "/api/v1/ships"
---

# Count vessels in a SAR scene

`POST /api/v1/ships`

## Request

- Base URL: `https://offnadir-delta.com`
- URL: `https://offnadir-delta.com/api/v1/ships`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Count vessel-like targets in ONE Sentinel-1 or NISAR scene over an area, using CFAR detection. Costs 5 tokens per detection (a NISAR granule converted for the first time adds 1, and needs the plan's NISAR access); a scene the worker refuses (an unsupported combination, an area with no usable sea) is not charged. Get `item_id` from GET /api/v1/imagery first. **Read `caveats` before quoting the count**: it says when the land mask was unavailable (shoreline structures may be counted as vessels), how far from the coast detections were excluded (the default excludes vessels alongside a quay), and when the scene covers only part of the requested area — a partial-coverage count must not be compared with a full one as though the difference were vessels. This measures one scene at one time; to track a berth over time, create a monitored area with metric `ships`.

## Request body

- object
  - `collection` 'sentinel-1-grd' | 'sentinel-1-rtc' | 'NISAR_L2_GCOV_PROVISIONAL_V1', required: Catalog collection of the scene: Sentinel-1, or NISAR L-band (the granule is converted to a COG first, which costs extra tokens the first time).
  - `item_id` string, required: STAC item id of the scene, as returned by GET /api/v1/imagery.
  - `bbox` number[]: Area to search within the scene, [lon_min, lat_min, lon_max, lat_max] (WGS84). Must be under 120,000 km².
  - `geometry` object: Alternative to bbox: a GeoJSON Polygon or MultiPolygon.
  - `algorithm_version` 'auto' | 'v2' | 'v3': Detector version. 'auto' picks the recommended version for the sensor.

## Response `200`

The detections, with the caveats that change what the count means.

- object
  - `summary` string
  - `count` integer
  - `ships` object: GeoJSON FeatureCollection of the detections.
  - `caveats` string[]
  - `scene` object
  - `processing` object: Algorithm version, configuration hash, land-mask source, sea ratio.
  - `meta` object

## Other responses

- `400`: Error response with a stable machine-readable code.
- `401`: Error response with a stable machine-readable code.
- `402`: Error response with a stable machine-readable code.
- `403`: Error response with a stable machine-readable code.
- `422`: Error response with a stable machine-readable code.
- `429`: Error response with a stable machine-readable code.

---

[API](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api.md) · [All operations](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api/revisions/5cf3f2bed5a2?raw)