openapi: 3.1.0
info:
title: API Reference async_process catalog_features 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_features
x-displayName: Features
description: 'This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Features specification. This extends OGC API - Features - Part 1: Core.'
paths:
/catalog/v1/collections/{collectionId}/items:
get:
tags:
- catalog_features
summary: fetch features
description: 'Fetch features of the feature collection with id `collectionId`.
Every feature in a dataset belongs to a collection. A dataset may
consist of multiple feature collections. A feature collection is often a
collection of features of a similar type, based on a common schema.'
operationId: getCatalogFeatures
parameters:
- $ref: '#/components/parameters/CatalogFeaturesCollectionId'
- $ref: '#/components/parameters/CatalogFeaturesLimit'
- $ref: '#/components/parameters/CatalogFeaturesBbox'
- $ref: '#/components/parameters/CatalogFeaturesDatetime'
responses:
'200':
$ref: '#/components/responses/CatalogFeaturesFeatures'
'400':
$ref: '#/components/responses/CatalogAccessControlIllegalCollection'
'403':
$ref: '#/components/responses/CatalogAccessControlInsufficientPermissions'
'404':
$ref: '#/components/responses/CatalogFeaturesNotFound'
'500':
$ref: '#/components/responses/CatalogFeaturesServerError'
security:
- OAuth2: []
/catalog/v1/collections/{collectionId}/items/{featureId}:
get:
tags:
- catalog_features
summary: fetch a single feature
description: 'Fetch the feature with id `featureId` in the feature collection
with id `collectionId`.'
operationId: getCatalogFeature
parameters:
- $ref: '#/components/parameters/CatalogFeaturesCollectionId'
- $ref: '#/components/parameters/CatalogFeaturesFeatureId'
responses:
'200':
$ref: '#/components/responses/CatalogFeaturesFeature'
'400':
$ref: '#/components/responses/CatalogAccessControlIllegalCollection'
'403':
$ref: '#/components/responses/CatalogAccessControlInsufficientPermissions'
'404':
$ref: '#/components/responses/CatalogFeaturesNotFound'
'500':
$ref: '#/components/responses/CatalogFeaturesServerError'
security:
- OAuth2: []
components:
schemas:
CatalogFeatureCollectionGeoJSON:
title: featureCollectionGeoJSON
type: object
required:
- type
- features
properties:
type:
type: string
enum:
- FeatureCollection
features:
type: array
items:
$ref: '#/components/schemas/CatalogFeatureGeoJSON'
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
CatalogPointGeoJSON:
title: pointGeoJSON
type: object
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Point
coordinates:
type: array
minItems: 2
items:
type: number
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.
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'
CatalogLinks:
title: links
type: array
items:
$ref: '#/components/schemas/CatalogLink'
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
CatalogFeaturesTimeStamp:
title: timeStamp
description: This property indicates the time and date when the response was generated.
type: string
format: date-time
example: '2017-08-17T08:05:32Z'
CatalogStacVersion:
title: STAC version
type: string
example: 1.0.0
CatalogFeatureGeoJSON:
title: featureGeoJSON
type: object
required:
- type
- geometry
- properties
properties:
type:
type: string
enum:
- Feature
geometry:
$ref: '#/components/schemas/CatalogGeometryGeoJSON'
properties:
type:
- object
- 'null'
CatalogItemType:
title: itemType
type: string
description: The GeoJSON type
enum:
- Feature
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
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'
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
CatalogItemId:
title: itemId
type: string
description: Provider identifier, a unique ID.
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
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
CatalogFeaturesFeatureCollectionGeoJSON:
title: featureCollectionGeoJSON
allOf:
- $ref: '#/components/schemas/CatalogFeatureCollectionGeoJSON'
- type: object
required:
- features
properties:
features:
type: array
items:
$ref: '#/components/schemas/CatalogItem'
links:
$ref: '#/components/schemas/CatalogLinks'
timeStamp:
$ref: '#/components/schemas/CatalogFeaturesTimeStamp'
numberReturned:
$ref: '#/components/schemas/CatalogFeaturesNumberReturned'
CatalogItem:
title: item
description: A GeoJSON Feature augmented with foreign members that contain values relevant to a STAC entity
type: object
required:
- stac_version
- id
- type
- geometry
- bbox
- links
- properties
- assets
properties:
stac_version:
$ref: '#/components/schemas/CatalogStacVersion'
stac_extensions:
$ref: '#/components/schemas/CatalogStacExtensions'
id:
$ref: '#/components/schemas/CatalogItemId'
bbox:
$ref: '#/components/schemas/CatalogBbox'
geometry:
$ref: '#/components/schemas/CatalogGeometryGeoJSON'
type:
$ref: '#/components/schemas/CatalogItemType'
links:
$ref: '#/components/schemas/CatalogLinks'
properties:
$ref: '#/components/schemas/CatalogProperties'
assets:
$ref: '#/components/schemas/CatalogAssets'
example:
stac_version: 1.0.0
stac_extensions:
- https://stac-extensions.github.io/eo/v1.0.0/schema.json
- https://stac-extensions.github.io/view/v1.0.0/schema.json
type: Feature
id: CS3-20160503_132131_05
bbox:
- -122.59750209
- 37.48803556
- -122.2880486
- 37.613537207
geometry:
type: Polygon
coordinates:
- - - -122.308150179
- 37.488035566
- - -122.597502109
- 37.538869539
- - -122.576687533
- 37.613537207
- - -122.2880486
- 37.562818007
- - -122.308150179
- 37.488035566
properties:
datetime: '2016-05-03T13:22:30.040Z'
title: A CS3 item
license: PDDL-1.0
providers:
- name: CoolSat
roles:
- producer
- licensor
url: https://cool-sat.com/
view:sun_azimuth: 168.7
eo:cloud_cover: 0.12
view:off_nadir: 1.4
platform: coolsat2
instruments:
- cool_sensor_v1
eo:bands: []
view:sun_elevation: 33.4
eo:gsd: 0.512
collection: CS3
links:
- rel: self
href: http://cool-sat.com/collections/CS3/items/20160503_132130_04
- rel: root
href: http://cool-sat.com/collections
- rel: parent
href: http://cool-sat.com/collections/CS3
- rel: collection
href: http://cool-sat.com/collections/CS3
assets:
analytic:
href: http://cool-sat.com/static-catalog/CS3/20160503_132130_04/analytic.tif
title: 4-Band Analytic
thumbnail:
href: http://cool-sat.com/static-catalog/CS3/20160503_132130_04/thumbnail.png
title: Thumbnail
CatalogGeometrycollectionGeoJSON:
title: geometrycollectionGeoJSON
type: object
required:
- type
- geometries
properties:
type:
type: string
enum:
- GeometryCollection
geometries:
type: array
items:
$ref: '#/components/schemas/CatalogGeometryGeoJSON'
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
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`.'
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
CatalogFeaturesNumberReturned:
title: numberReturned
description: 'The number of features in the feature collection.
A server may omit this information in a response, if the information
about the number of features is not known or difficult to compute.
If the value is provided, the value must be identical to the number
of items in the "features" array.'
type: integer
minimum: 0
example: 10
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
parameters:
CatalogFeaturesCollectionId:
name: collectionId
in: path
description: local identifier of a collection
required: true
schema:
type: string
CatalogFeaturesLimit:
name: limit
in: query
description: 'The optional limit parameter recommends the number of items that should be present 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.'
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
style: form
explode: false
CatalogFeaturesDatetime:
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: false
schema:
type: string
style: form
explode: false
CatalogFeaturesBbox:
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.'
required: false
schema:
type: array
oneOf:
- minItems: 4
maxItems: 4
- minItems: 6
maxItems: 6
items:
type: number
style: form
explode: false
CatalogFeaturesFeatureId:
name: featureId
in: path
description: local identifier of a feature
required: true
schema:
type: string
responses:
CatalogAccessControlIllegalCollection:
description: Illegal collection.
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogException'
CatalogFeaturesServerError:
description: A server error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogException'
CatalogFeaturesFeature:
description: 'fetch the feature with id `featureId` in the feature collection
with id `collectionId`'
content:
application/geo+json:
schema:
$ref: '#/components/schemas/CatalogItem'
example:
stac_version: 1.0.0
stac_extensions:
- https://stac-extensions.github.io/eo/v1.0.0/schema.json
- https://stac-extensions.github.io/projection/v1.0.0/schema.json
id: S2B_MSIL2A_20201229T101329_N0214_R022_T33TUK_20201229T115442
type: Feature
geometry:
type: MultiPolygon
crs:
type: name
properties:
name: urn:ogc:def:crs:OGC::CRS84
coordinates:
- - - - 12.456873618680804
- 45.12550485074961
- - 12.499663722139168
- 44.138006014975964
- - 13.153277241744092
- 44.15044712021016
- - 13.558241653952589
- 45.144727105915536
- - 12.456873618680804
- 45.12550485074961
bbox:
- 12.456873618680804
- 44.138006014975964
- 13.558241653952589
- 45.144727105915536
properties:
datetime: '2020-12-29T10:18:19Z'
platform: sentinel-2b
instruments:
- msi
constellation: sentinel-2
gsd: 10
eo:cloud_cover: 93.93
proj:epsg: 32633
proj:bbox:
- 300000
- 4890240
- 409800
- 5000040
proj:geometry:
type: MultiPolygon
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
assets:
data:
href: s3://sentinel-s2-l2a/tiles/33/T/UK/2020/12/29/0/
title: s3
type: inode/directory
collection: sentinel-2-l2a
links:
- href: https://services.sentinel-hub.com/catalog/v1/
rel: root
type: application/json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a/items/S2B_MSIL2A_20201229T101329_N0214_R022_T33TUK_20201229T115442
rel: self
type: application/geo+json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a
rel: parent
type: application/json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a
rel: collection
type: application/json
- href: https://scihub.copernicus.eu/dhus/odata/v1/Products('1da14794-939f-4ede-b490-cd3a2348b495')/$value
rel: derived_from
title: scihub download
CatalogFeaturesFeatures:
description: 'The response is a document consisting of features in the collection.
The features included in the response are determined by the server
based on the query parameters of the request. To support access to
larger collections without overloading the client, the API supports
paged access with links to the next page, if more features are selected
that the page size.
The `bbox` and `datetime` parameter can be used to select only a
subset of the features in the collection (the features that are in the
bounding box or time interval). The `bbox` parameter matches all features
in the collection that are not associated with a location, too. The
`datetime` parameter matches all features in the collection that are
not associated with a time stamp or interval, too.
The `limit` parameter may be used to control the subset of the
selected features that should be returned in the response, the page size.
Each page may include information about the number of selected and
returned features (`numberMatched` and `numberReturned`) as well as
links to support paging (link relation `next`).'
content:
application/geo+json:
schema:
$ref: '#/components/schemas/CatalogFeaturesFeatureCollectionGeoJSON'
example:
type: FeatureCollection
features:
- stac_version: 1.0.0
stac_extensions:
- https://stac-extensions.github.io/eo/v1.0.0/schema.json
- https://stac-extensions.github.io/projection/v1.0.0/schema.json
id: S2B_MSIL2A_20201229T101329_N0214_R022_T33TUK_20201229T115442
type: Feature
geometry:
type: MultiPolygon
crs:
type: name
properties:
name: urn:ogc:def:crs:OGC::CRS84
coordinates:
- - - - 12.456873618680804
- 45.12550485074961
- - 12.499663722139168
- 44.138006014975964
- - 13.153277241744092
- 44.15044712021016
- - 13.558241653952589
- 45.144727105915536
- - 12.456873618680804
- 45.12550485074961
bbox:
- 12.456873618680804
- 44.138006014975964
- 13.558241653952589
- 45.144727105915536
properties:
datetime: '2020-12-29T10:18:19Z'
platform: sentinel-2b
instruments:
- msi
constellation: sentinel-2
gsd: 10
eo:cloud_cover: 93.93
proj:epsg: 32633
proj:bbox:
- 300000
- 4890240
- 409800
- 5000040
proj:geometry:
type: MultiPolygon
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
assets:
data:
href: s3://sentinel-s2-l2a/tiles/33/T/UK/2020/12/29/0/
title: s3
type: inode/directory
collection: sentinel-2-l2a
links:
- href: https://services.sentinel-hub.com/catalog/v1/
rel: root
type: application/json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a/items/S2B_MSIL2A_20201229T101329_N0214_R022_T33TUK_20201229T115442
rel: self
type: application/geo+json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a
rel: parent
type: application/json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a
rel: collection
type: application/json
- href: https://scihub.copernicus.eu/dhus/odata/v1/Products('1da14794-939f-4ede-b490-cd3a2348b495')/$value
rel: derived_from
title: scihub download
links:
- href: https://services.sentinel-hub.com/catalog/v1/
rel: root
type: application/json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a/items?bbox=13,45,14,46&limit=1&datetime=2020-12-10T00:00:00Z/2020-12-30T00:00:00Z
rel: self
type: application/geo+json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a
rel: parent
type: application/json
- href: https://services.sentinel-hub.com/catalog/v1/collections/sentinel-2-l2a/items?limit=1&next=1&datetime=2020-12-10T00:00:00Z/2020-12-30T00:00:00Z&bbox=13,45,14,46
rel: next
type: application/geo+json
title: Next set of results
timeStamp: '2023-05-19T12:54:40.429059Z'
numberReturned: 1
CatalogFeaturesNotFound:
description: The requested URI was not found.
CatalogAccessControlInsufficientPermissions:
description: Insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogException'
securitySchemes:
OAuth2:
type: oauth2
description: "### Authentication\n\nMore about the authentication <a href=\"https://docs.planet.com/develop/authentication/\" target=\"_blank\">here</a>.\n\nTo get an access token using curl:\n\n```\ncurl --request POST \\\n --url https://services.sentinel-hub.com/auth/realms/main/protocol/openid-connect/token \\\n --header \"content-type: application/x-www-form-urlencoded\" \\\n --data \"grant_type=client_credentials&client_id=<your client id>&client_secret=<your client secret>\"\n```\n"
flows:
clientCredentials:
tokenUrl: https://services.sentinel-hub.com/auth/realms/main/protocol/openid-connect/token
scopes:
SH: Sentinel Hub
x-tagGroups:
- name: Process API
tags:
- process
- name: Catalog
tags:
- catalog_core
- catalog_collections
- catalog_features
- catalog_item_search
- name: Async API
tags:
- async_process
- name: BatchV2 API
tags:
- batch_v2_process
- batch_v2_tiling_grid
- name: Stats API
tags:
- statistical
- name: Batch Stats API
tags:
- batch_statistical
- name: BYOC
tags:
- byoc_collection
- byoc_tile
- name: Zarr Import API
tags:
- zarr_collection
- zarr_array
- name: TPDI
tags:
- dataimport_search
- dataimport_product
- dataimport_order
- dataimport_delivery
- dataimport_tile_delivery
- dataimport_subscription
- dataimport_subscription_delivery
- dataimport_subscription_tile_delivery
- dataimport_quota
- name: Metadata
tags:
- metadata_location
- metadata_collection