<!-- Source: https://docs.geopera.com/api-reference/operations/catalog · Markdown for LLMs -->

<!-- AUTO-GENERATED by scripts/generate-api-reference.cjs from the committed OpenAPI spec. Do not edit by hand. -->

# Catalog & search operations

Browse and search commercial and public satellite imagery.

Each operation below is reachable at `POST /v1/op/{operation_id}` or the resource path `POST /v1/{resource}/{action}`, with a Bearer token (a `gpra_` API key or a session token). Back to the [Operations Reference](/api-reference/operations) index.

## `catalog.federated_search`

Search every data source covering the AOI in one query (merged, type-tagged).

| | |
|---|---|
| **Scope** | `catalog:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.federated_search`  ·  `POST /v1/catalog/federated_search` |
| **Python / TypeScript** | `client.catalog.federated_search(…)` |
| **CLI** | `geopera catalog federated-search …` |

**Request** — `FederatedSearchInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `collections` | array of string | — |  |
| `ids` | array of string | — |  |
| `datetime` | string | — |  |
| `limit` | integer | — |  |
| `query` | object | — |  |
| `bbox` | array of number | — |  |
| `intersects` | object | — |  |
| `full_catalog` | boolean | — |  |
| `source_ids` | array of string | — |  |
| `data_types` | array of string | — |  |

**Response** — `FederatedSearchOutput`.

## `catalog.granule_points`

Extract a 3D point cloud (lon/lat/elev/attribute) from a GEDI or ICESat-2 granule.

| | |
|---|---|
| **Scope** | `catalog:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.granule_points`  ·  `POST /v1/catalog/granule_points` |
| **Python / TypeScript** | `client.catalog.granule_points(…)` |
| **CLI** | `geopera catalog granule-points …` |

**Request** — `GranulePointsInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `collection` | string | yes | Registry collection id, e.g. |
| `href` | string | yes | HTTPS .h5 granule URL from the STAC item (Earthdata-hosted) |
| `bbox` | array of number | yes | AOI [west, south, east, north] |
| `max_points` | integer | — | Uniform-subsample ceiling |
| `clip_polygon` | object | — | AOI GeoJSON Polygon/MultiPolygon — points are clipped to this exact shape, not just the bbox |

**Response** — `GranulePointsOutput`.

## `catalog.image.quicklook`

Resolve + 307-redirect to a scene's quicklook (external host).

| | |
|---|---|
| **Scope** | `catalog:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.image.quicklook`  ·  `POST /v1/catalog/image/quicklook` |
| **Python / TypeScript** | `client.catalog.image.quicklook(…)` |
| **CLI** | `geopera catalog image quicklook …` |

**Request** — `ImageAssetInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `host_name` | string | yes |  |
| `image_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.image.thumbnail`

Resolve + 307-redirect to a scene's thumbnail (external host).

| | |
|---|---|
| **Scope** | `catalog:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.image.thumbnail`  ·  `POST /v1/catalog/image/thumbnail` |
| **Python / TypeScript** | `client.catalog.image.thumbnail(…)` |
| **CLI** | `geopera catalog image thumbnail …` |

**Request** — `ImageAssetInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `host_name` | string | yes |  |
| `image_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.info.landsat`

Landsat scene metadata (parsed id fields + available visualizations).

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.info.landsat`  ·  `POST /v1/catalog/info/landsat` |
| **Python / TypeScript** | `client.catalog.info.landsat(…)` |
| **CLI** | `geopera catalog info landsat …` |

**Request** — `SceneInfoInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `scene_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.info.naip`

NAIP item metadata from the Element84 STAC.

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.info.naip`  ·  `POST /v1/catalog/info/naip` |
| **Python / TypeScript** | `client.catalog.info.naip(…)` |
| **CLI** | `geopera catalog info naip …` |

**Request** — `SceneInfoInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `scene_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.info.sample`

Sample scene metadata (sensor + on-disk STAC + bands + thumbnail).

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.info.sample`  ·  `POST /v1/catalog/info/sample` |
| **Python / TypeScript** | `client.catalog.info.sample(…)` |
| **CLI** | `geopera catalog info sample …` |

**Request** — `SampleInfoInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `provider` | string | yes |  |
| `scene_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.info.sentinel`

Sentinel-2 scene metadata (parsed id + live COG info + available visualizations).

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.info.sentinel`  ·  `POST /v1/catalog/info/sentinel` |
| **Python / TypeScript** | `client.catalog.info.sentinel(…)` |
| **CLI** | `geopera catalog info sentinel …` |

**Request** — `SceneInfoInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `scene_id` | string | yes |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.provider.samples`

List sample scenes for a provider (paged).

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.provider.samples`  ·  `POST /v1/catalog/provider/samples` |
| **Python / TypeScript** | `client.catalog.provider.samples(…)` |
| **CLI** | `geopera catalog provider samples …` |

**Request** — `ProviderSamplesInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `provider` | string | yes |  |
| `limit` | integer | — |  |
| `offset` | integer | — |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.providers.list`

List on-disk sample-data providers (+ registered sensors).

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.providers.list`  ·  `POST /v1/catalog/providers/list` |
| **Python / TypeScript** | `client.catalog.providers.list(…)` |
| **CLI** | `geopera catalog providers list …` |

**Request** — `VizListInput` _(see the OpenAPI schema for fields)_.

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.search`

Search a commercial-imagery host's catalog (STAC, price-enriched).

| | |
|---|---|
| **Scope** | `catalog:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.search`  ·  `POST /v1/catalog/search` |
| **Python / TypeScript** | `client.catalog.search(…)` |
| **CLI** | `geopera catalog search …` |

**Request** — `CatalogSearchInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `collections` | array of string | — |  |
| `ids` | array of string | — |  |
| `datetime` | string | — |  |
| `limit` | integer | — |  |
| `query` | object | — |  |
| `bbox` | array of number | — |  |
| `intersects` | object | — |  |
| `full_catalog` | boolean | — |  |
| `host_name` | string | yes |  |
| `next` | string | — |  |

**Response** — `CatalogSearchOutput`.

## `catalog.search_stream`

Invoke Catalog Search Stream.

| | |
|---|---|
| **Scope** | `catalog:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.search_stream`  ·  `POST /v1/catalog/search_stream` |
| **Python / TypeScript** | `client.catalog.search_stream(…)` |
| **CLI** | `geopera catalog search-stream …` |

**Request** — a free-form JSON object.

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.sources.list`

List every searchable data source + its collections (the dataset registry).

| | |
|---|---|
| **Scope** | `catalog:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.sources.list`  ·  `POST /v1/catalog/sources/list` |
| **Python / TypeScript** | `client.catalog.sources.list(…)` |
| **CLI** | `geopera catalog sources list …` |

**Request** — `SourcesListInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `data_type` | string | — |  |
| `scope` | string | — |  |
| `country` | string | — |  |

**Response** — `SourcesListOutput`.

## `catalog.tile.render`

Render a public satellite XYZ tile (sentinel/landsat/naip/sample) — unbilled, unauthenticated.

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.tile.render`  ·  `POST /v1/catalog/tile/render` |
| **Python / TypeScript** | `client.catalog.tile.render(…)` |
| **CLI** | `geopera catalog tile render …` |

**Request** — `CatalogTileInput`

| Field | Type | Required | Description |
|---|---|---|---|
| `collection` | string | yes |  |
| `scene_id` | string | yes |  |
| `visualization` | string | yes |  |
| `z` | integer | yes |  |
| `x` | integer | yes |  |
| `y` | integer | yes |  |
| `format` | string | yes |  |
| `provider` | string | — |  |
| `quality` | integer | — |  |
| `aoi_clip` | string | — |  |
| `aoi_clip_body` | object | — |  |
| `expression` | string | — |  |
| `colormap` | string | — |  |
| `rescale` | string | — |  |

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.vendors.list`

List catalog vendors + host⇄pricing-vendor identifiers.

| | |
|---|---|
| **Scope** | `catalog:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.vendors.list`  ·  `POST /v1/catalog/vendors/list` |
| **Python / TypeScript** | `client.catalog.vendors.list(…)` |
| **CLI** | `geopera catalog vendors list …` |

**Request** — `_Empty` _(see the OpenAPI schema for fields)_.

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.viz.landsat`

List available Landsat visualizations.

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.viz.landsat`  ·  `POST /v1/catalog/viz/landsat` |
| **Python / TypeScript** | `client.catalog.viz.landsat(…)` |
| **CLI** | `geopera catalog viz landsat …` |

**Request** — `VizListInput` _(see the OpenAPI schema for fields)_.

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.

## `catalog.viz.naip`

List available NAIP visualizations.

| | |
|---|---|
| **Scope** | `tiles:read` |
| **Side-effect** | read |
| **HTTP** | `POST /v1/op/catalog.viz.naip`  ·  `POST /v1/catalog/viz/naip` |
| **Python / TypeScript** | `client.catalog.viz.naip(…)` |
| **CLI** | `geopera catalog viz naip …` |

**Request** — `VizListInput` _(see the OpenAPI schema for fields)_.

**Response** — a streaming or binary payload (NDJSON / file / tile). Call the HTTP endpoint directly; the JSON SDK return does not apply.