Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Reference async_process Catalog Item Search API
version: 1.0.0
contact:
name: Sentinel Hub
description: '**NOTE:** _Asynchronous Processing API is currently in beta release._
'
servers:
- url: https://services.sentinel-hub.com
tags:
- name: catalog_item_search
x-displayName: Item Search
description: This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Item Search specification.
paths:
/catalog/v1/search:
get:
summary: Search STAC items with simple filtering.
operationId: getCatalogItemSearch
description: 'Retrieve Items matching filters. Intended as a shorthand API for simple
queries.
This method is required to implement.
If this endpoint is implemented on a server, it is required to add a
link referring to this endpoint with `rel` set to `search` to the
`links` array in `GET /`. As `GET` is the default method, the `method`
may not be set explicitly in the link.'
tags:
- catalog_item_search
parameters:
- $ref: '#/components/parameters/CatalogItemSearchBbox'
- $ref: '#/components/parameters/CatalogItemSearchIntersects'
- $ref: '#/components/parameters/CatalogItemSearchDatetime'
- $ref: '#/components/parameters/CatalogItemSearchLimit'
- $ref: '#/components/parameters/CatalogItemSearchIds'
- $ref: '#/components/parameters/CatalogItemSearchCollectionsArray'
- $ref: '#/components/parameters/CatalogItemSearchFieldsFields'
- $ref: '#/components/parameters/CatalogItemSearchFilterFilter'
- $ref: '#/components/parameters/CatalogItemSearchDistinctDistinct'
responses:
'200':
description: A feature collection.
content:
application/geo+json:
schema:
allOf:
- $ref: '#/components/schemas/CatalogItemSearchItemCollectionItemCollection'
- $ref: '#/components/schemas/CatalogItemSearchContextItemCollection'
example:
type: FeatureCollection
features:
- bbox:
- 12.456873618680804
- 44.138006014975964
- 13.558241653952589
- 45.144727105915536
id: S2B_MSIL2A_20201229T101329_N0214_R022_T33TUK_20201229T115442
type: Feature
properties:
proj:epsg: 32633
datetime: '2020-12-29T10:18:19Z'
instruments:
- msi
constellation: sentinel-2
proj:geometry:
crs:
type: name
properties:
name: urn:ogc:def:crs:EPSG::32633
coordinates:
- - - - 300000.99988415383
- 5000039.000148304
- - 300000.99989785976
- 4890241.000124758
- - 352314.4884079728
- 4890241.000125499
- - 386653.8629171661
- 5000039.000149397
- - 300000.99988415383
- 5000039.000148304
type: MultiPolygon
eo:cloud_cover: 93.93
gsd: 10
proj:bbox:
- 300000
- 4890240
- 409800
- 5000040
platform: sentinel-2b
links:
- href: https://services.sentinel-hub.com/catalog/v1/search?collections=sentinel-2-l2a&bbox=13,45,14,46&limit=1&datetime=2020-12-10T00:00:00Z/2020-12-30T00:00:00Z&filter=eo:cloud_cover>90&fields=id,type,-geometry,bbox,properties,-links,-assets
rel: self
type: application/geo+json
- href: https://services.sentinel-hub.com/catalog/v1/search?collections=sentinel-2-l2a&bbox=13,45,14,46&limit=1&datetime=2020-12-10T00:00:00Z/2020-12-30T00:00:00Z&filter=eo:cloud_cover>90&fields=id,type,-geometry,bbox,properties,-links,-assets&next=1
rel: next
type: application/geo+json
title: Next set of results
context:
next: 1
limit: 1
returned: 1
'400':
$ref: '#/components/responses/CatalogAccessControlIllegalCollection'
'403':
$ref: '#/components/responses/CatalogAccessControlInsufficientPermissions'
'500':
$ref: '#/components/responses/CatalogError'
security:
- OAuth2: []
post:
summary: Search STAC items with full-featured filtering.
operationId: postCatalogItemSearch
description: 'Retrieve items matching filters. Intended as the standard, full-featured
query API.
This method is optional to implement, but recommended.
If this endpoint is implemented on a server, it is required to add a
link referring to this endpoint with `rel` set to `search` and `method`
set to `POST` to the `links` array in `GET /`.'
tags:
- catalog_item_search
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CatalogItemSearchSearchBody'
- $ref: '#/components/schemas/CatalogItemSearchFieldsSearchBody'
- $ref: '#/components/schemas/CatalogItemSearchFilterSearchBody'
- $ref: '#/components/schemas/CatalogItemSearchDistinctSearchBody'
example:
collections:
- sentinel-2-l2a
bbox:
- 13
- 45
- 14
- 46
datetime: 2020-12-10T00:00:00Z/2020-12-30T00:00:00Z
fields:
include:
- id
- type
- bbox
- properties
exclude:
- geometry
- links
- assets
filter:
op: '>'
args:
- property: eo:cloud_cover
- 90
filter-lang: cql2-json
limit: 1
responses:
'200':
description: A feature collection.
content:
application/geo+json:
schema:
allOf:
- $ref: '#/components/schemas/CatalogItemSearchItemCollectionItemCollection'
- $ref: '#/components/schemas/CatalogItemSearchContextItemCollection'
example:
type: FeatureCollection
features:
- bbox:
- 12.456873618680804
- 44.138006014975964
- 13.558241653952589
- 45.144727105915536
id: S2B_MSIL2A_20201229T101329_N0214_R022_T33TUK_20201229T115442
type: Feature
properties:
proj:epsg: 32633
datetime: '2020-12-29T10:18:19Z'
instruments:
- msi
constellation: sentinel-2
proj:geometry:
crs:
type: name
properties:
name: urn:ogc:def:crs:EPSG::32633
coordinates:
- - - - 300000.99988415383
- 5000039.000148304
- - 300000.99989785976
- 4890241.000124758
- - 352314.4884079728
- 4890241.000125499
- - 386653.8629171661
- 5000039.000149397
- - 300000.99988415383
- 5000039.000148304
type: MultiPolygon
eo:cloud_cover: 93.93
gsd: 10
proj:bbox:
- 300000
- 4890240
- 409800
- 5000040
platform: sentinel-2b
links:
- href: https://services.sentinel-hub.com/catalog/v1/search
rel: self
type: application/geo+json
- href: https://services.sentinel-hub.com/catalog/v1/search
rel: next
type: application/geo+json
title: Next set of results
method: POST
body:
next: 1
merge: true
context:
next: 1
limit: 1
returned: 1
'400':
$ref: '#/components/responses/CatalogAccessControlIllegalCollection'
'403':
$ref: '#/components/responses/CatalogAccessControlInsufficientPermissions'
'500':
$ref: '#/components/responses/CatalogError'
security:
- OAuth2: []
components:
parameters:
CatalogItemSearchFieldsFields:
name: fields
x-stac-api-fragment: fields
in: query
description: '**Extension:** Fields
Determines the shape of the features in the response'
required: false
schema:
type: string
example: id,type,-geometry,bbox,properties,-links,-assets
style: form
explode: false
CatalogItemSearchIds:
name: ids
in: query
description: Array of Item ids to return.
required: false
schema:
$ref: '#/components/schemas/CatalogItemSearchIds'
explode: false
CatalogItemSearchDistinctDistinct:
name: distinct
x-stac-api-fragment: distinct
in: query
description: '**Extension:** Distinct
Return distinct values of specified property.'
required: false
schema:
type: string
style: form
explode: false
CatalogItemSearchBbox:
name: bbox
in: query
description: 'Only features that have a geometry that intersects the bounding box are selected.
The bounding box is provided as four or six numbers, depending on
whether the coordinate reference system includes a vertical axis (height
or depth):
* Lower left corner, coordinate axis 1
* Lower left corner, coordinate axis 2
* Minimum value, coordinate axis 3 (optional)
* Upper right corner, coordinate axis 1
* Upper right corner, coordinate axis 2
* Maximum value, coordinate axis 3 (optional)
The coordinate reference system of the values is WGS 84
longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
For WGS 84 longitude/latitude the values are in most cases the sequence
of minimum longitude, minimum latitude, maximum longitude and maximum
latitude. However, in cases where the box spans the antimeridian the
first value (west-most box edge) is larger than the third value
(east-most box edge).
If the vertical axis is included, the third and the sixth number are
the bottom and the top of the 3-dimensional bounding box.
If a feature has multiple spatial geometry properties, it is the
decision of the server whether only a single spatial geometry property
is used to determine the extent or all relevant geometries.
Example: The bounding box of the New Zealand Exclusive Economic Zone in
WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be
represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as
`bbox=160.6,-55.95,-170,-25.89`.'
required: false
schema:
type: array
oneOf:
- minItems: 4
maxItems: 4
- minItems: 6
maxItems: 6
items:
type: number
style: form
explode: false
example:
- 13
- 45
- 14
- 46
CatalogItemSearchDatetime:
name: datetime
in: query
description: 'Either a date-time or an interval, open or closed. Date and time expressions
adhere to RFC 3339. Open intervals are expressed using double-dots.
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
Only features that have a temporal property that intersects the value of
`datetime` are selected.
If a feature has multiple temporal properties, it is the decision of the
server whether only a single temporal property is used to determine
the extent or all relevant temporal properties.'
required: true
schema:
type: string
style: form
explode: false
example: 2020-12-10T00:00:00Z/2020-12-30T00:00:00Z
CatalogItemSearchLimit:
name: limit
in: query
description: 'The optional limit parameter recommends the number of items that should be present in the response document.
Only items are counted that are on the first level of the collection in the response document.
Nested objects contained within the explicitly requested items must not be counted.
Minimum = 1. Maximum = 100. Default = 10.'
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
style: form
explode: false
example: 1
CatalogItemSearchCollectionsArray:
name: collections
in: query
description: 'Array of Collection IDs to include in the search for items.
Only Item objects in one of the provided collections will be searched
'
required: true
schema:
$ref: '#/components/schemas/CatalogItemSearchCollectionsArray'
explode: false
example:
- sentinel-2-l2a
CatalogItemSearchIntersects:
name: intersects
in: query
description: 'The optional intersects parameter filters the result Items in the same was as bbox, only with
a GeoJSON Geometry rather than a bbox.'
required: false
schema:
$ref: '#/components/schemas/CatalogGeometryGeoJSON'
style: form
explode: false
CatalogItemSearchFilterFilter:
name: filter
x-stac-api-fragment: filter
in: query
description: '**Extension:** Filter
A CQL2 filter expression for filtering items.'
required: false
schema:
$ref: '#/components/schemas/CatalogItemSearchFilterFilterCql2Text'
example: eo:cloud_cover>90
schemas:
CatalogItemSearchDatetimeInterval:
title: datetimeInterval
type: string
description: 'Either a date-time or an interval, open or closed. Date and time expressions
adhere to RFC 3339. Open intervals are expressed using double-dots.
Examples:
* A date-time: "2018-02-12T23:20:50Z"
* A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
* Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
Only features that have a temporal property that intersects the value of
`datetime` are selected.
If a feature has multiple temporal properties, it is the decision of the
server whether only a single temporal property is used to determine
the extent or all relevant temporal properties.'
example: 2018-02-12T00:00:00Z/2018-03-18T12:31:12Z
CatalogItemSearchIntersectsFilter:
title: intersectsFilter
type: object
description: Only returns items that intersect with the provided polygon.
properties:
intersects:
$ref: '#/components/schemas/CatalogGeometryGeoJSON'
CatalogItemSearchDatetimeFilter:
title: datetimeFilter
description: An object representing a date+time based filter.
type: object
properties:
datetime:
$ref: '#/components/schemas/CatalogItemSearchDatetimeInterval'
CatalogGeometrycollectionGeoJSON:
title: geometrycollectionGeoJSON
type: object
required:
- type
- geometries
properties:
type:
type: string
enum:
- GeometryCollection
geometries:
type: array
items:
$ref: '#/components/schemas/CatalogGeometryGeoJSON'
CatalogItemSearchFilterSearchBody:
title: searchBody
type: object
x-stac-api-fragment: filter
description: '**Extension:** Filter
A filter for properties in Items.'
properties:
filter:
$ref: '#/components/schemas/CatalogItemSearchFilterFilterCql2Json'
filter-lang:
$ref: '#/components/schemas/CatalogItemSearchFilterFilterLang'
filter-crs:
$ref: '#/components/schemas/CatalogItemSearchFilterFilterCrs'
CatalogStacVersion:
title: STAC version
type: string
example: 1.0.0
CatalogBbox:
title: bbox
description: 'Only features that have a geometry that intersects the bounding box are
selected. The bounding box is provided as four or six numbers,
depending on whether the coordinate reference system includes a
vertical axis (elevation or depth):
* Lower left corner, coordinate axis 1
* Lower left corner, coordinate axis 2
* Lower left corner, coordinate axis 3 (optional)
* Upper right corner, coordinate axis 1
* Upper right corner, coordinate axis 2
* Upper right corner, coordinate axis 3 (optional)
The coordinate reference system of the values is WGS84
longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
For WGS84 longitude/latitude the values are in most cases the sequence
of minimum longitude, minimum latitude, maximum longitude and maximum
latitude. However, in cases where the box spans the antimeridian the
first value (west-most box edge) is larger than the third value
(east-most box edge).
If a feature has multiple spatial geometry properties, it is the
decision of the server whether only a single spatial geometry property
is used to determine the extent or all relevant geometries.
Example: The bounding box of the New Zealand Exclusive Economic Zone in
WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be
represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as
`bbox=160.6,-55.95,-170,-25.89`.'
type: array
minItems: 4
maxItems: 6
items:
type: number
example:
- -110
- 39.5
- -105
- 40.5
CatalogItemSearchLimitFilter:
title: limitFilter
type: object
description: Only returns maximum number of results (page size)
properties:
limit:
$ref: '#/components/schemas/CatalogItemSearchLimit'
CatalogItemSearchFilterFilterCql2Text:
title: filter-cql2-text
description: 'A CQL2 filter expression in the ''cql2-text'' encoding.
'
type: string
CatalogItemSearchLimit:
title: limit
type: integer
minimum: 1
example: 10
default: 10
maximum: 100
description: 'The optional limit parameter limits the number of items that are presented in the response document.
If the limit parameter value is greater than advertised limit maximum, the server must return the
maximum possible number of items, rather than responding with an error.
Only items are counted that are on the first level of the collection in the response document.
Nested objects contained within the explicitly requested items must not be counted.
Minimum = 1. Maximum = 100. Default = 10.'
Cql2ComparisonPredicate:
title: comparisonPredicate
oneOf:
- $ref: '#/components/schemas/Cql2BinaryComparisonPredicate'
- $ref: '#/components/schemas/Cql2IsBetweenPredicate'
CatalogAssets:
title: assets
type: object
additionalProperties:
type: object
required:
- href
properties:
href:
type: string
format: url
description: Link to the asset object
title:
type: string
description: Displayed title
example: Thumbnail
description:
type: string
description: 'Multi-line description to explain the asset.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation.'
example: Small 256x256px PNG thumbnail for a preview.
type:
type: string
description: Media type of the asset
example: image/png
roles:
type: array
items:
type: string
description: Purposes of the asset
example:
- thumbnail
CatalogGeometryGeoJSON:
title: geometryGeoJSON
oneOf:
- $ref: '#/components/schemas/CatalogPointGeoJSON'
- $ref: '#/components/schemas/CatalogMultipointGeoJSON'
- $ref: '#/components/schemas/CatalogLinestringGeoJSON'
- $ref: '#/components/schemas/CatalogMultilinestringGeoJSON'
- $ref: '#/components/schemas/CatalogPolygonGeoJSON'
- $ref: '#/components/schemas/CatalogMultipolygonGeoJSON'
- $ref: '#/components/schemas/CatalogGeometrycollectionGeoJSON'
CatalogItemSearchFieldsFields:
title: fields
description: 'The include and exclude members specify an array of
property names that are either included or excluded
from the result, respectively. If both include and
exclude are specified, include takes precedence.
Values should include the full JSON path of the property.
'
type: object
properties:
include:
type: array
items:
type: string
exclude:
type: array
items:
type: string
example:
include:
- id
- properties.eo:cloud_cover
exclude:
- geometry
- properties.datetime
CatalogItemSearchIds:
title: ids
type: array
description: Array of Item ids to return.
items:
type: string
CatalogItemSearchFieldsSearchBody:
title: searchBody
type: object
x-stac-api-fragment: fields
description: '**Extension:** Fields
Determines the shape of the features in the response'
properties:
fields:
$ref: '#/components/schemas/CatalogItemSearchFieldsFields'
CatalogMultilinestringGeoJSON:
title: multilinestringGeoJSON
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiLineString
coordinates:
type: array
items:
type: array
minItems: 2
items:
type: array
minItems: 2
items:
type: number
CatalogItemSearchItemCollectionItemCollection:
title: itemCollection
description: A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
type: object
required:
- features
- type
properties:
type:
type: string
enum:
- FeatureCollection
features:
type: array
items:
$ref: '#/components/schemas/CatalogItem'
links:
type: array
description: An array of links. Can be used for pagination, e.g. by providing a link with the `next` relation type.
items:
$ref: '#/components/schemas/CatalogLink'
example:
- rel: next
href: https://services.sentinel-hub.com/catalog/v1/search?next=10
CatalogProperties:
title: properties
type: object
required:
- datetime
description: provides the core metadata fields plus extensions
properties:
datetime:
$ref: '#/components/schemas/CatalogDatetime'
additionalProperties:
description: Any additional properties added in via Item specification or extensions.
CatalogLinks:
title: links
type: array
items:
$ref: '#/components/schemas/CatalogLink'
CatalogDatetime:
title: datetime
description: 'The searchable date and time of the assets, in UTC.
It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
`null` is allowed, but requires `start_datetime` and `end_datetime` from common metadata to be set.'
oneOf:
- type: string
format: date-time
- type: 'null'
example: '2018-02-12T00:00:00Z'
CatalogLinestringGeoJSON:
title: linestringGeoJSON
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- LineString
coordinates:
type: array
minItems: 2
items:
type: array
minItems: 2
items:
type: number
CatalogItemSearchCollectionsFilter:
title: collectionsFilter
type: object
description: Only returns the collections specified
properties:
collections:
$ref: '#/components/schemas/CatalogItemSearchCollectionsArray'
CatalogMultipointGeoJSON:
title: multipointGeoJSON
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiPoint
coordinates:
type: array
items:
type: array
minItems: 2
items:
type: number
CatalogItemSearchContextItemCollection:
title: itemCollection
type: object
description: '**Extension:** Context
Augments lists of resources with the number of returned and matches resource and the given limit for the request.'
x-stac-api-fragment: context
properties:
context:
type: object
required:
- returned
properties:
next:
type: integer
minimum: 0
example: 1
limit:
type: integer
minimum: 0
example: 1
returned:
type: integer
minimum: 0
example: 1
CatalogItemId:
title: itemId
type: string
description: Provider identifier, a unique ID.
Cql2BooleanExpression:
title: booleanExpression
oneOf:
- $ref: '#/components/schemas/Cql2AndExpression'
- $ref: '#/components/schemas/Cql2NotExpression'
- $ref: '#/components/schemas/Cql2ComparisonPredicate'
Cql2IsBetweenPredicate:
title: isBetweenPredicate
type: object
required:
- op
- args
properties:
op:
type: string
enum:
- between
args:
$ref: '#/components/schemas/Cql2IsBetweenOperands'
Cql2CharacterExpression:
title: characterExpression
oneOf:
- type: string
- $ref: '#/components/schemas/Cql2PropertyRef'
Cql2PropertyRef:
title: propertyRef
type: object
required:
- property
properties:
property:
type: string
CatalogMultipolygonGeoJSON:
title: multipolygonGeoJSON
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiPolygon
coordinates:
type: array
items:
type: array
items:
type: array
minItems: 4
items:
type: array
minItems: 2
items:
type: number
CatalogItemSearchFilterFilterLang:
title: filter-lang
description: 'The CQL2 filter encoding that the ''filter'' value uses.
'
type: string
enum:
- cql2-text
- cql2-json
Cql2IsBetweenOperands:
title: isBetweenOperands
type: array
minItems: 3
maxItems: 3
items:
$ref: '#/components/schemas/Cql2NumericExpression'
CatalogItemType:
title: itemType
type: string
description: The GeoJSON type
enum:
- Feature
Cql2NotExpression:
title: cql2NotExpression
type: object
required:
- op
- args
properties:
op:
type: string
enum:
- not
args:
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/Cql2BooleanExpression'
CatalogException:
title: exception
type: object
description: 'Information about the exception: an error code plus an optional description.'
required:
- code
properties:
code:
type: string
description:
type: string
Cql2NumericExpression:
title: numericExpression
oneOf:
- type: number
- $ref: '#/components/schemas/Cql2PropertyRef'
Cql2AndExpression:
title: andExpression
type: object
required:
- op
- args
properties:
op:
type: string
enum:
- and
args:
type: array
minItems: 2
items:
$ref: '#/components/schemas/Cql2BooleanExpression'
CatalogLink:
title: Link
type: object
required:
- href
- rel
properties:
href:
type: string
format: uri
description: The location of the resource
rel:
type: string
description: Relation type of the link
type:
type: string
description: The media type of the resource
title:
type: string
description: Title of the resource
method:
type: string
enum:
- GET
- POST
default: GET
description: Specifies the HTTP method that the resource expects
headers:
type: object
description: Object key values pairs they map to headers
example:
Accept: application/json
body:
type: object
description: For POST requests, the resource can specify the HTTP body as a JSON object.
merge:
type: boolean
default: false
description: 'This is only valid when the server is responding to POST request.
If merge is true, the client is expected to merge the body value
into the current request body before following the link.
This avoids passing large post bodies back and forth when following
links, particularly for navigating pages through the `POST /search`
endpoint.
NOTE: To support form encoding it is expected that a client be able
to merge in the key value pairs specified as JSON
`{"next": "token"}` will become `&next=token`.'
CatalogStacExtensions:
title: STAC extensions
type: array
uniqueItems: true
items:
anyOf:
- title: Reference to a JSON Schema
type: string
format: uri
- title: Reference to a core extension
type: string
CatalogPolygonGeoJSON:
title: polygonGeoJSON
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Polygon
coordinates:
type: array
items:
type: array
minItems: 4
items:
type: array
minItems: 2
items:
type: number
Cql2ScalarExpression:
title: scalarExpression
oneOf:
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sentinel-hub/refs/heads/main/openapi/sentinel-hub-catalog-item-search-api-openapi.yml