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 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
`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
`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
`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
`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
`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.