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 here.\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=&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