API Reference (1.0.0)

Download OpenAPI specification:Download

This page contains the documentation on how to use sentinel hub services through API calls.

Note: This documentation is not complete

Process

Make sure to use the appropriate end-point for each of the datasets, e.g. for Landsat, Sentinel-3, etc.

Process

Authorizations:
OAuth2
header Parameters
Accept
string

Sets response type and has priority over the type defined in the output object of the request. Possible values are image/jpeg, image/png, image/tiff, application/json, application/tar, application/x-tar, multipart/mixed, and application/octet-stream.

Request Body schema:
required
object (ProcessRequestInput)
object (ProcessRequestOutput)
evalscript
required
string

Your evalscript. For details, click here.

Responses

Response Schema:
string <image/jpeg> (Jpeg image)

Request samples

Content type
{
  • "input": {
    },
  • "output": {
    },
  • "evalscript": "string"
}

Response samples

Content type
No sample

Core

This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Core specification. Any service that implements this endpoint to allow discovery of spatiotemporal assets can be considered a STAC API.

Make sure to use the appropriate end-point for each of the datasets, e.g. for Landsat, Sentinel-3, etc.

landing page

Returns the root STAC Catalog or STAC Collection that is the entry point for users to browse with STAC Browser or for search engines to crawl. This can either return a single STAC Collection or more commonly a STAC catalog.

The landing page provides links to the API definition (link relations service-desc and service-doc) and the STAC records such as collections/catalogs (link relation child) or items (link relation item).

Extensions may add additional links with new relation types.

Responses

Response Schema: application/json
stac_version
required
string (CatalogStacVersion)
Array of Reference to a JSON Schema (string) or Reference to a core extension (string) (CatalogStacExtensions) unique
type
required
string
id
required
string
title
string
description
required
string
required
Array of objects (CatalogLinks)
conformsTo
required
Array of strings

A list of all conformance classes implemented by the server. In addition to the STAC-specific conformance classes, all OGC-related conformance classes listed at GET /conformances must be listed here. This entry should mirror what GET /conformances returns, if implemented.

Response samples

Content type
application/json
{}

information about specifications that this API conforms to

A list of all conformance classes specified in a standard that the server conforms to.

Responses

Response Schema: application/json
conformsTo
required
Array of strings

A list of all conformance classes implemented by the server. In addition to the STAC-specific conformance classes, all OGC-related conformance classes listed at GET /conformances must be listed here. This entry should mirror what GET /conformances returns, if implemented.

Collections

This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Collections specification. This is a subset of the STAC API - Features specification.

the feature collections in the dataset

A body of Feature Collections that belong or are used together with additional links. Request may not return the full set of metadata per Feature Collection.

Authorizations:
OAuth2

Responses

Response Schema: application/json
required
Array of objects (CatalogLinks)
required
Array of objects (collection)

Response samples

Content type
application/json
{}

describe the feature collection with id `collectionId`

A single Feature Collection for the given if collectionId. Request this endpoint to get a full list of metadata for the Feature Collection.

Authorizations:
OAuth2
path Parameters
collectionId
required
string

local identifier of a collection

Responses

Response Schema: application/json
stac_version
required
string (CatalogStacVersion)
Array of Reference to a JSON Schema (string) or Reference to a core extension (string) (CatalogStacExtensions) unique
type
required
string
id
required
string

identifier of the collection used, for example, in URIs

title
string

human readable title of the collection

description
required
string

Detailed multi-line description to fully explain the catalog or collection. CommonMark 0.29 syntax MAY be used for rich text representation.

keywords
Array of strings

List of keywords describing the collection.

license
required
string (CatalogLicense)

License(s) of the data as a SPDX License identifier. Alternatively, use proprietary if the license is not on the SPDX license list or various if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the license link relation type.

Non-SPDX licenses SHOULD add a link to the license text with the license relation in the links section. The license text MUST NOT be provided as a value of this field. If there is no public license URL available, it is RECOMMENDED to host the license text and link to it.

required
object (CatalogExtent)

The extent of the features in the collection. In the Core only spatial and temporal extents are specified. Extensions may add additional members to represent other extents, for example, thermal or pressure ranges.

The first item in the array describes the overall extent of the data. All subsequent items describe more precise extents, e.g., to identify clusters of data. Clients only interested in the overall extent will only need to access the first item in each array.

Array of objects (CatalogProviders)

A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list.

required
Array of objects (CatalogLinks)
object

Summaries are either a unique set of all available values or statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. The range can specify the potential range of values, but it is recommended to be as precise as possible. The set of values must contain at least one element and it is strongly recommended to list all values. It is recommended to list as many properties as reasonable so that consumers get a full overview of the Collection. Properties that are covered by the Collection specification (e.g. providers and license) may not be repeated in the summaries.

Response samples

Content type
application/json
{}

Get the JSON Schema defining the list of variable terms that can be used in CQL2 expressions.

This endpoint returns a list of variable terms that can be used in CQL2 expressions. The precise definition of this can be found in the OGC API - Features - Part 3: Filtering and the Common Query Language (CQL) specification.

Authorizations:
OAuth2
path Parameters
collectionId
required
string

ID of Collection

Responses

Response Schema: application/schema+json
object

Response samples

Content type
application/schema+json
{}

Features

This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Features specification. This extends OGC API - Features - Part 1: Core.

fetch features

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.

Authorizations:
OAuth2
path Parameters
collectionId
required
string

local identifier of a collection

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

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.

Array of numbers or Array of numbers

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.

datetime
string

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.

Responses

Response Schema: application/geo+json
type
required
string
Value: "FeatureCollection"
required
Array of objects (featureGeoJSON)
Array of objects (CatalogLinks)
timeStamp
string <date-time> (CatalogFeaturesTimeStamp)

This property indicates the time and date when the response was generated.

numberReturned
integer (CatalogFeaturesNumberReturned) >= 0

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.

Response samples

Content type
application/geo+json
{}

fetch a single feature

Fetch the feature with id featureId in the feature collection with id collectionId.

Authorizations:
OAuth2
path Parameters
collectionId
required
string

local identifier of a collection

featureId
required
string

local identifier of a feature

Responses

Response Schema: application/geo+json
stac_version
required
string (CatalogStacVersion)
Array of Reference to a JSON Schema (string) or Reference to a core extension (string) (CatalogStacExtensions) unique
id
required
string (CatalogItemId)

Provider identifier, a unique ID.

bbox
required
Array of numbers (CatalogBbox) [ 4 .. 6 ] items

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.

required
pointGeoJSON (object) or multipointGeoJSON (object) or linestringGeoJSON (object) or multilinestringGeoJSON (object) or polygonGeoJSON (object) or multipolygonGeoJSON (object) or geometrycollectionGeoJSON (object) (CatalogGeometryGeoJSON)
type
required
string (CatalogItemType)
Value: "Feature"

The GeoJSON type

required
Array of objects (CatalogLinks)
required
object (CatalogProperties)

provides the core metadata fields plus extensions

required
object (CatalogAssets)

Response samples

Content type
application/geo+json
{}

Search STAC items with simple filtering.

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.

Authorizations:
OAuth2
query Parameters
Array of numbers or Array of numbers
Example: bbox=13,45,14,46

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.

pointGeoJSON (object) or multipointGeoJSON (object) or linestringGeoJSON (object) or multilinestringGeoJSON (object) or polygonGeoJSON (object) or multipolygonGeoJSON (object) or geometrycollectionGeoJSON (object) (geometryGeoJSON)

The optional intersects parameter filters the result Items in the same was as bbox, only with a GeoJSON Geometry rather than a bbox.

datetime
required
string
Example: datetime=2020-12-10T00:00:00Z/2020-12-30T00:00:00Z

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.

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=1

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.

ids
Array of strings (ids)

Array of Item ids to return.

collections
required
Array of strings (collectionsArray) = 1 items
Example: collections=sentinel-2-l2a

Array of Collection IDs to include in the search for items. Only Item objects in one of the provided collections will be searched

fields
string
Example: fields=id,type,-geometry,bbox,properties,-links,-assets

Extension: Fields

Determines the shape of the features in the response

filter
string (filter-cql2-text)
Example: filter=eo:cloud_cover>90

Extension: Filter

A CQL2 filter expression for filtering items.

distinct
string

Extension: Distinct

Return distinct values of specified property.

Responses

Response Schema: application/geo+json
type
required
string
Value: "FeatureCollection"
required
Array of objects (item)
Array of objects (Link)

An array of links. Can be used for pagination, e.g. by providing a link with the next relation type.

object

Response samples

Content type
application/geo+json
{}

Search STAC items with full-featured filtering.

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

Authorizations:
OAuth2
Request Body schema: application/json
bbox
Array of numbers (CatalogBbox) [ 4 .. 6 ] items

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.

datetime
required
string (CatalogItemSearchDatetimeInterval)

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.

pointGeoJSON (object) or multipointGeoJSON (object) or linestringGeoJSON (object) or multilinestringGeoJSON (object) or polygonGeoJSON (object) or multipolygonGeoJSON (object) or geometrycollectionGeoJSON (object) (CatalogGeometryGeoJSON)
collections
required
Array of strings (CatalogItemSearchCollectionsArray) = 1 items

Array of Collection IDs to include in the search for items. Only Item objects in one of the provided collections will be searched.

ids
Array of strings (CatalogItemSearchIds)

Array of Item ids to return.

limit
integer (CatalogItemSearchLimit) [ 1 .. 100 ]

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.

object (CatalogItemSearchFieldsFields)

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.

andExpression (object) or cql2NotExpression (object) or (comparisonPredicate (binaryComparisonPredicate (object) or isBetweenPredicate (object))) (CatalogItemSearchFilterFilterCql2Json)
filter-lang
string (CatalogItemSearchFilterFilterLang)
Enum: "cql2-text" "cql2-json"

The CQL2 filter encoding that the 'filter' value uses.

filter-crs
string <uri> (CatalogItemSearchFilterFilterCrs)

The coordinate reference system (CRS) used by spatial literals in the 'filter' value. The only value that STAC APIs must accept is 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'.

distinct
string (CatalogItemSearchDistinctDistinct)

Return distinct values of specified property.

Responses

Response Schema: application/geo+json
type
required
string
Value: "FeatureCollection"
required
Array of objects (item)
Array of objects (Link)

An array of links. Can be used for pagination, e.g. by providing a link with the next relation type.

object

Request samples

Content type
application/json
{
  • "collections": [
    ],
  • "bbox": [
    ],
  • "datetime": "2020-12-10T00:00:00Z/2020-12-30T00:00:00Z",
  • "fields": {
    },
  • "filter": {
    },
  • "filter-lang": "cql2-json",
  • "limit": 1
}

Response samples

Content type
application/geo+json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "links": [],
  • "context": {
    }
}

Async Process

NOTE: Asynchronous Processing API is currently in beta release.

Submit a new async process request

Authorizations:
OAuth2
Request Body schema: application/json
required
object (ProcessRequestInput)
required
object (AsyncProcessRequestOutput)
evalscript
string

Your evalscript. For details, click here.

Either this or evalscriptReference parameter is required.

object (ObjectStorageInfo)

Reference to your evalscript stored in an object storage. For details, click here.

Either this or evalscript parameter is required.

Responses

Response Schema: application/json
id
string <UUID>

UUID of the submitted request

status
string
Value: "RUNNING"

Status of the request

Request samples

Content type
application/json
{
  • "input": {
    },
  • "output": {
    },
  • "evalscript": "string",
  • "evalscriptReference": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "RUNNING"
}

Get status of the request

The status of the request will only be returned while it's running. After completion (either succeed or failure) this endpoint will return 404.

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response Schema: application/json
id
string <UUID>

UUID of the submitted request

status
string
Value: "RUNNING"

Status of the request

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "RUNNING"
}

Process

Submit new batch processing request

Authorizations:
OAuth2
Request Body schema:
required
object (ProcessRequestForBatch)

Batch processing equivalent of the Process request.

tilingGridId
integer <int64>
Deprecated

This parameter was moved to tilingGrid

object (TilingGridSettings)

Tiling grid settings.

resolution
number <double>
Deprecated

This parameter was moved to tilingGrid.

object (BatchProcessOutput)

Specifies the tile output paths where the results shall be written. Required unless bucketName or zarrOutput is specified.

bucketName
string

Simplified alternative for specifying where the results shall be written, where only the bucket name is specified. Specifying some-bucket as bucketName is equivalent to specifying s3://some-bucket as the defaultTilePath in output.

object (BatchZarrParameters)

Specifies Zarr creation parameters.

If this parameter is specified, all outputs in processRequest must be of the type zarr/array and neither bucketName nor output can be specified. With Zarr output only WGS84 and LAEA grids are supported.

Note: Zarr output is currently in beta release. Both the request parameters and the output are likely to change in the future.

description
string

Optional description that can be used to keep track of requests

Responses

Response Schema: application/json
id
string <uuid>

Identifier

userId
string <uuid>

User that submitted the request

accountId
string <uuid>

Account that submitted the request

created
string <date-time>

Creation time of the request in ISO 8601

required
object (ProcessRequestForBatch)

Batch processing equivalent of the Process request.

tilingGridId
integer <int64>
Deprecated

This parameter was moved to tilingGrid

object (TilingGridSettings)

Tiling grid settings.

resolution
number <double>
Deprecated

This parameter was moved to tilingGrid.

object (BatchProcessOutput)

Specifies the tile output paths where the results shall be written. Required unless bucketName or zarrOutput is specified.

bucketName
string

Simplified alternative for specifying where the results shall be written, where only the bucket name is specified. Specifying some-bucket as bucketName is equivalent to specifying s3://some-bucket as the defaultTilePath in output.

object (BatchZarrParameters)

Specifies Zarr creation parameters.

If this parameter is specified, all outputs in processRequest must be of the type zarr/array and neither bucketName nor output can be specified. With Zarr output only WGS84 and LAEA grids are supported.

Note: Zarr output is currently in beta release. Both the request parameters and the output are likely to change in the future.

description
string

Optional description that can be used to keep track of requests

valueEstimate
number <double>

Estimated processing value (cost) of the request in processing units. The accuracy of the estimate depends on your request, as described in the documentation.

tileCount
integer <int32>

Number of output tiles

tileWidthPx
integer <int32>

Tile width in pixels

tileHeightPx
integer <int32>

Tile height in pixels

userAction
string
Enum: "NONE" "ANALYSE" "START" "CANCEL"

Last user action on the request

userActionUpdated
string <date-time>

Time of last user action update in ISO 8601

status
string
Enum: "CREATED" "ANALYSING" "ANALYSIS_DONE" "PROCESSING" "DONE" "PARTIAL" "FAILED" "CANCELED"

Current processing status of the request

error
string

Error description for requests that were submitted but failed during analysis or processing

Request samples

Content type
{
  • "processRequest": {
    },
  • "tilingGridId": 0,
  • "tilingGrid": {
    },
  • "resolution": 0,
  • "output": {
    },
  • "bucketName": "string",
  • "zarrOutput": {
    },
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "created": "2019-08-24T14:15:22Z",
  • "processRequest": {
    },
  • "tilingGridId": 0,
  • "tilingGrid": {
    },
  • "resolution": 0,
  • "output": {
    },
  • "bucketName": "string",
  • "zarrOutput": {
    },
  • "description": "string",
  • "valueEstimate": 0,
  • "tileCount": 0,
  • "tileWidthPx": 0,
  • "tileHeightPx": 0,
  • "userAction": "NONE",
  • "userActionUpdated": "2019-08-24T14:15:22Z",
  • "status": "CREATED",
  • "error": "string"
}

Query batch process requests

Authorizations:
OAuth2
query Parameters
collectionId
string <uuid>

Filter batch process requests by the collectionId of batch collection. Omit to get all batch process requests, including those not linked to any collection.

count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

search
string

Optional search query. Either a single word to search for or multiple words separated by the | (or) and & (and) operators. If omitted, all items are returned.

sort
string
Enum: "created" "created:desc" "status" "status:desc"

Sort the batch process requests by given field. Omit for default ordering.

Responses

Response Schema: application/json
Array of objects (BatchProcessRequest)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Retrieve a single batch process request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response Schema: application/json
id
string <uuid>

Identifier

userId
string <uuid>

User that submitted the request

accountId
string <uuid>

Account that submitted the request

created
string <date-time>

Creation time of the request in ISO 8601

required
object (ProcessRequestForBatch)

Batch processing equivalent of the Process request.

tilingGridId
integer <int64>
Deprecated

This parameter was moved to tilingGrid

object (TilingGridSettings)

Tiling grid settings.

resolution
number <double>
Deprecated

This parameter was moved to tilingGrid.

object (BatchProcessOutput)

Specifies the tile output paths where the results shall be written. Required unless bucketName or zarrOutput is specified.

bucketName
string

Simplified alternative for specifying where the results shall be written, where only the bucket name is specified. Specifying some-bucket as bucketName is equivalent to specifying s3://some-bucket as the defaultTilePath in output.

object (BatchZarrParameters)

Specifies Zarr creation parameters.

If this parameter is specified, all outputs in processRequest must be of the type zarr/array and neither bucketName nor output can be specified. With Zarr output only WGS84 and LAEA grids are supported.

Note: Zarr output is currently in beta release. Both the request parameters and the output are likely to change in the future.

description
string

Optional description that can be used to keep track of requests

valueEstimate
number <double>

Estimated processing value (cost) of the request in processing units. The accuracy of the estimate depends on your request, as described in the documentation.

tileCount
integer <int32>

Number of output tiles

tileWidthPx
integer <int32>

Tile width in pixels

tileHeightPx
integer <int32>

Tile height in pixels

userAction
string
Enum: "NONE" "ANALYSE" "START" "CANCEL"

Last user action on the request

userActionUpdated
string <date-time>

Time of last user action update in ISO 8601

status
string
Enum: "CREATED" "ANALYSING" "ANALYSIS_DONE" "PROCESSING" "DONE" "PARTIAL" "FAILED" "CANCELED"

Current processing status of the request

error
string

Error description for requests that were submitted but failed during analysis or processing

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "created": "2019-08-24T14:15:22Z",
  • "processRequest": {
    },
  • "tilingGridId": 0,
  • "tilingGrid": {
    },
  • "resolution": 0,
  • "output": {
    },
  • "bucketName": "string",
  • "zarrOutput": {
    },
  • "description": "string",
  • "valueEstimate": 0,
  • "tileCount": 0,
  • "tileWidthPx": 0,
  • "tileHeightPx": 0,
  • "userAction": "NONE",
  • "userActionUpdated": "2019-08-24T14:15:22Z",
  • "status": "CREATED",
  • "error": "string"
}

Update a batch process request

Only the requests that are not currently being processed nor waiting to be processed can be updated.

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Request Body schema: application/json
object

Modified output object. If omitted, no values within output will be changed.

description
string

Optional description that can be used to keep track of requests. If omitted, the description will not be changed.

Responses

Response Schema: application/json
id
string <uuid>

Identifier

userId
string <uuid>

User that submitted the request

accountId
string <uuid>

Account that submitted the request

created
string <date-time>

Creation time of the request in ISO 8601

required
object (ProcessRequestForBatch)

Batch processing equivalent of the Process request.

tilingGridId
integer <int64>
Deprecated

This parameter was moved to tilingGrid

object (TilingGridSettings)

Tiling grid settings.

resolution
number <double>
Deprecated

This parameter was moved to tilingGrid.

object (BatchProcessOutput)

Specifies the tile output paths where the results shall be written. Required unless bucketName or zarrOutput is specified.

bucketName
string

Simplified alternative for specifying where the results shall be written, where only the bucket name is specified. Specifying some-bucket as bucketName is equivalent to specifying s3://some-bucket as the defaultTilePath in output.

object (BatchZarrParameters)

Specifies Zarr creation parameters.

If this parameter is specified, all outputs in processRequest must be of the type zarr/array and neither bucketName nor output can be specified. With Zarr output only WGS84 and LAEA grids are supported.

Note: Zarr output is currently in beta release. Both the request parameters and the output are likely to change in the future.

description
string

Optional description that can be used to keep track of requests

valueEstimate
number <double>

Estimated processing value (cost) of the request in processing units. The accuracy of the estimate depends on your request, as described in the documentation.

tileCount
integer <int32>

Number of output tiles

tileWidthPx
integer <int32>

Tile width in pixels

tileHeightPx
integer <int32>

Tile height in pixels

userAction
string
Enum: "NONE" "ANALYSE" "START" "CANCEL"

Last user action on the request

userActionUpdated
string <date-time>

Time of last user action update in ISO 8601

status
string
Enum: "CREATED" "ANALYSING" "ANALYSIS_DONE" "PROCESSING" "DONE" "PARTIAL" "FAILED" "CANCELED"

Current processing status of the request

error
string

Error description for requests that were submitted but failed during analysis or processing

Request samples

Content type
application/json
{
  • "output": {
    },
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "created": "2019-08-24T14:15:22Z",
  • "processRequest": {
    },
  • "tilingGridId": 0,
  • "tilingGrid": {
    },
  • "resolution": 0,
  • "output": {
    },
  • "bucketName": "string",
  • "zarrOutput": {
    },
  • "description": "string",
  • "valueEstimate": 0,
  • "tileCount": 0,
  • "tileWidthPx": 0,
  • "tileHeightPx": 0,
  • "userAction": "NONE",
  • "userActionUpdated": "2019-08-24T14:15:22Z",
  • "status": "CREATED",
  • "error": "string"
}

Delete a batch process request

Deletes a batch process request if it:

  • is not currently being processed or analysed,
  • has not been confirmed for processing or analysis,
  • has no successfully processed tiles.

Requests that have been confirmed or are currently being processed or analysed must be canceled before deletion. Requests with processed tiles cannot be deleted.

path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Request analysis of a batch process request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Start (confirm) processing of a batch process request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Cancel a batch process request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Restart a partially processed request

Restart processing of failed tiles in a partially processed request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Collection

Create a new batch collection

Authorizations:
OAuth2
Request Body schema: application/json
name
required
string

Collection name

s3Bucket
required
string

S3 bucket where data will get ingested

Responses

Response Schema: application/json
id
string <uuid>
userId
string <uuid>
accountId
string <uuid>
name
string
s3Bucket
string
object
object (BYOCCollectionAdditionalData)
created
string or null

The date when the collection was created.

Request samples

Content type
application/json
{
  • "name": "string",
  • "s3Bucket": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "name": "string",
  • "s3Bucket": "string",
  • "batchData": {
    },
  • "additionalData": {
    },
  • "created": "string"
}

Query batch collections

Authorizations:
OAuth2
query Parameters
count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

search
string

Optional search query. Either a single word to search for or multiple words separated by the | (or) and & (and) operators. If omitted, all items are returned.

Responses

Response Schema: application/json
Array of objects (BatchCollection)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Retrieve a single batch collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Collection ID

Responses

Response Schema: application/json
id
string <uuid>
userId
string <uuid>
accountId
string <uuid>
name
string
s3Bucket
string
object
object (BYOCCollectionAdditionalData)
created
string or null

The date when the collection was created.

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "name": "string",
  • "s3Bucket": "string",
  • "batchData": {
    },
  • "additionalData": {
    },
  • "created": "string"
}

Update a batch collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Collection ID

Request Body schema: application/json
name
string

Collection name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete a batch collection

Deletes a batch collection if it is not being used by any batch process request, except for possible FAILED and CANCELED requests.

path Parameters
collectionId
required
string <uuid>

Collection ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Tile

Get all tiles of a batch process

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

query Parameters
status
string
Enum: "PENDING" "SCHEDULED" "QUEUED" "PROCESSING" "PROCESSED" "FAILED"

Only tiles with this status will be returned. Omit to get all tiles.

count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

Responses

Response Schema: application/json
Array of objects (BatchTile)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Retrieve a single tile for the specific batch process

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

tileId
required
integer <int64>

Tile ID

Responses

Response Schema: application/json
id
integer <int64>

Identifier

requestId
string <uuid>

ID of the request the tile belongs to

object (Polygon)

Geometry of the grid tile that this request tile corresponds to.

Note that this may differ from the geometry of the tile's ouput raster due to bufferX/bufferY parameters of your request and due to reprojection from the tile's coordinate reference system to WGS84. The exact output raster geometry can be calculated from the tile's origin, width, height, and your request parameters resolution, bufferX and bufferY.

object (BatchTileOrigin)

Coordinates of the tile origin (lower left corner) in the tile's CRS.

status
string
Enum: "PENDING" "SCHEDULED" "QUEUED" "PROCESSING" "PROCESSED" "FAILED"

Current processing status of the tile

error
string

Error description for tiles that failed during processing.

cost
number <double>

Tile processing cost (PU)

Response samples

Content type
application/json
{
  • "id": 0,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "geometry": {
    },
  • "origin": {
    },
  • "status": "PENDING",
  • "error": "string",
  • "cost": 0
}

Tiling grid

Get properties of all supported tiling grids

Authorizations:
OAuth2
query Parameters
count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

Responses

Response Schema: application/json
Array of objects (TilingGridDescriptor)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get properties of a single tiling grid

Authorizations:
OAuth2
path Parameters
id
required
integer <int64>

Tilinggrids ID

Responses

Response Schema: application/json
id
integer <int64>

Identifier

name
string
object (TilingGridDescriptorProperties)

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "properties": {
    }
}

Statistical

Submit statistical request

Authorizations:
OAuth2
Request Body schema:
required
object (ProcessRequestInput)
required
object (StatisticalRequestAggregation)

Specifies how data is aggregated and processed before statistics is calculated. timeRange and aggregationInterval combined define sampling intervals in time dimension. Width/height or resx/resy combined with input.bounds define a sample matrix (i.e. "image") in spatial dimension.

object (StatisticalRequestCalculations)

Define which statistics and histogram to calculate. It can be specified differently for each evalscript output. If omitted only the basic statistic (min, max, mean, stDev) will be calculated.

Responses

Response Schema: application/json
Array of objects

Statistics for intervals, where data is available.

Request samples

Content type
{
  • "input": {
    },
  • "aggregation": {
    },
  • "calculations": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Statistical

Submit a new statistical batch request

Authorizations:
OAuth2
Request Body schema:
required
object (BatchStatisticalInput)
required
object (BatchStatisticalRequestAggregation)

Specifies how data is aggregated and processed before statistics is calculated. timeRange and aggregationInterval combined define sampling intervals in time dimension. Width/height or resx/resy combined with input.bounds define a sample matrix (i.e. "image") in spatial dimension.

object (StatisticalRequestCalculations)

Define which statistics and histogram to calculate. It can be specified differently for each evalscript output. If omitted only the basic statistic (min, max, mean, stDev) will be calculated.

required
object (ObjectStorageOutputInfo)

Storage location where the results shall be written.

Responses

Response Schema: application/json
id
string <uuid>

UUID of the submitted request.

status
string
Enum: "CREATED" "ANALYSING" "ANALYSIS_DONE" "PROCESSING" "DONE" "FAILED" "STOPPED" "PARTIAL"

Current processing status of the request. Must NOT be specified when creating new requests

error
string

Description of error in case the request failed.

completionPercentage
number
lastUpdated
string <date-time>
costPu
number

Cost of the request in processing units

created
string <date-time>

Creation time of the request

stoppedStatusReason
string
Enum: "OUT_OF_PU" "USER_ACTION"

The reason for request having status STOPPED.

object (BatchStatisticalRequest)
userAction
string
Enum: "NONE" "ANALYSE" "START" "STOP"

Last user action on the request.

userActionUpdated
string <date-time>

Date of the last user action on the request

domainAccountId
string <uuid>

Request samples

Content type
{
  • "input": {
    },
  • "aggregation": {
    },
  • "calculations": {
    },
  • "output": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "CREATED",
  • "error": "string",
  • "completionPercentage": 0,
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "costPu": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "stoppedStatusReason": "OUT_OF_PU",
  • "request": {
    },
  • "userAction": "NONE",
  • "userActionUpdated": "2019-08-24T14:15:22Z",
  • "domainAccountId": "4e1699b2-af74-455a-818d-6f1ec31a6d19"
}

Query statistical batch requests

Authorizations:
OAuth2
query Parameters
count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

sort
string
Enum: "created" "created:desc" "status" "status:desc"

Sort the statistical batch requests by given field. Omit for default ordering.

Responses

Response Schema: application/json
Array of objects (BatchStatisticsTaskDto)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Retrieve a single batch statistical request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response Schema: application/json
id
string <uuid>

UUID of the submitted request.

status
string
Enum: "CREATED" "ANALYSING" "ANALYSIS_DONE" "PROCESSING" "DONE" "FAILED" "STOPPED" "PARTIAL"

Current processing status of the request. Must NOT be specified when creating new requests

error
string

Description of error in case the request failed.

completionPercentage
number
lastUpdated
string <date-time>
costPu
number

Cost of the request in processing units

created
string <date-time>

Creation time of the request

stoppedStatusReason
string
Enum: "OUT_OF_PU" "USER_ACTION"

The reason for request having status STOPPED.

object (BatchStatisticalRequest)
userAction
string
Enum: "NONE" "ANALYSE" "START" "STOP"

Last user action on the request.

userActionUpdated
string <date-time>

Date of the last user action on the request

domainAccountId
string <uuid>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "CREATED",
  • "error": "string",
  • "completionPercentage": 0,
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "costPu": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "stoppedStatusReason": "OUT_OF_PU",
  • "request": {
    },
  • "userAction": "NONE",
  • "userActionUpdated": "2019-08-24T14:15:22Z",
  • "domainAccountId": "4e1699b2-af74-455a-818d-6f1ec31a6d19"
}

Retrieve the status of a batch statistical request.

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response Schema: application/json
id
string <uuid>

UUID of the submitted request.

status
string
Enum: "CREATED" "ANALYSING" "ANALYSIS_DONE" "PROCESSING" "DONE" "FAILED" "STOPPED" "PARTIAL"

Current processing status of the request. Must NOT be specified when creating new requests

error
string

Description of error in case the request failed.

completionPercentage
number
lastUpdated
string <date-time>
costPu
number

Cost of the request in processing units

created
string <date-time>

Creation time of the request

stoppedStatusReason
string
Enum: "OUT_OF_PU" "USER_ACTION"

The reason for request having status STOPPED.

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "CREATED",
  • "error": "string",
  • "completionPercentage": 0,
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "costPu": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "stoppedStatusReason": "OUT_OF_PU"
}

Request analysis of a batch statistical request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Start (confirm) processing of a batch statistical request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Stop a batch statistical request

Authorizations:
OAuth2
path Parameters
requestId
required
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Collection

Create a collection

Authorizations:
OAuth2
Request Body schema: application/json
name
required
string
s3Bucket
required
string
isConfigured
boolean

It's set to true, if the collection has bands.

noData
number
object (BYOCCollectionAdditionalData)

Responses

Response Schema: application/json
object (BYOCCollection)

Request samples

Content type
application/json
{
  • "name": "string",
  • "s3Bucket": "string",
  • "isConfigured": true,
  • "noData": 0,
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query collections

Authorizations:
OAuth2
query Parameters
count
integer <int32> [ 1 .. 100 ]

Number of items to retrieve.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

search
string

Optional search query. Either a single word to search for or multiple words separated by the | (or) and & (and) operators. If omitted, all items are returned.

Responses

Response Schema: application/json
Array of objects (BYOCCollection)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get a collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Responses

Response Schema: application/json
object (BYOCCollection)

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
Request Body schema: application/json
name
required
string
s3Bucket
required
string

Can only be changed if the collection is empty.

noData
number

If the value is not provided, the old one gets deleted.

object (BYOCCollectionAdditionalData)

If provided, overwrites the current bands property of the collection:

  • to rename band(s), provide the current value of the "bands" property with only the name(s) of one or more bands changed
  • to set noData value(s), provide the current value of the "bands" property with only the noData value(s) of one or more bands changed
  • to remove band(s), provide the current value of the "bands" property but leave out the band(s) you wish to remove
  • to remove all bands, you must first empty the collection, then provide "additionalData" without the "bands" property or with an empty "bands" property.

Keep in mind that:

  • bands cannot be added nor their other properties ("bitDepth", "bandIndex", etc) changed once you add a tile.
  • once sample format is set you cannot change it, and tiles ingested from then on need be in the set sample format.

If "additionalData" is omitted, the bands will not be changed.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "s3Bucket": "string",
  • "noData": 0,
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete a collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Copy collection tiles

Copies ingested tiles from one collection to another, but only those whose path isn't present in the target collection.

You need to have access to both source and target collections, and target collection needs to have either the same band names and types, or it should have no bands.

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
query Parameters
toCollection
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Tile

Create a tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
Request Body schema: application/json
path
required
string^([^/](/?[^/])*)?$

The path within the bucket where the files are. Can also use the '(BAND)' placeholder when the file names contain more than just the band name.

Polygon (object) or MultiPolygon (object)

The geometry as GeoJSON which outlines the area that has data.

If it isn't specified, it is automatically set to the intersection of all file bounding boxes.

You may specify this in any CRS, however it will be converted to CRS84.

After ingestion is complete, this stays in CRS84 on our system, however, for you convenience, we convert and return this in the CRS of the tile.

sensingTime
string or null <date-time>

The sensing time of the tile in ISO 8601 but without sub-millisecond precision.

object (BYOCTileAdditionalData)

Responses

Response Schema: application/json
object (BYOCTile)

Request samples

Content type
application/json
{
  • "path": "folder/prefix_(BAND)",
  • "tileGeometry": {
    },
  • "coverGeometry": {
    },
  • "sensingTime": "2019-08-24T14:15:22Z",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get collection tiles

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
query Parameters
count
integer <int32> [ 1 .. 100 ]

Number of items to retrieve.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

sort
string
Enum: "created:asc" "created:desc" "path:asc" "path:desc"

Get tiles sorted by created date or path, and either in ascending or descending order.

path
string

Get the tile with the exact path. Returns a single tile or no tile, if there's none with given path.

status
string (BYOCTileStatus)
Enum: "WAITING" "QUEUED" "INGESTING" "INGESTED" "FAILED"

Get only the files with the given status.

Responses

Response Schema: application/json
Array of objects (BYOCTile)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get a tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>

Responses

Response Schema: application/json
object (BYOCTile)

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>
Request Body schema: application/json
object or object (Geometry)
sensingTime
string or null <date-time>

The sensing time of the tile in ISO 8601 but without sub-millisecond precision.

Responses

Request samples

Content type
application/json
{
  • "coverGeometry": {
    },
  • "sensingTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete a tile

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Reingest a tile

Initiates reingestion of a tile.

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
tileId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Collection

Create a Zarr collection

Authorizations:
OAuth2
Request Body schema: application/json
name
required
string
s3Bucket
required
string

The S3 bucket where the Zarr is stored.

path
required
string

The prefix within the bucket where the Zarr is stored. Must end with '/' but not start with it and must contain a Zarr group.

crs
required
string

Native CRS of the Zarr. See also Sentinel Hub CRS support.

Responses

Response Schema: application/json
object <ZarrCollection> (ZarrCollection)

Request samples

Content type
application/json
{
  • "name": "string",
  • "s3Bucket": "string",
  • "path": "string",
  • "crs": "string",
  • "envelope": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query Zarr collections

Authorizations:
OAuth2
query Parameters
count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

search
string

Optional query to search Zarr collections by name. If omitted, all items are returned.

Responses

Response Schema: aplication/json
Array of objects <ZarrCollection> (ZarrCollection) [ items <ZarrCollection > ]

Response samples

Content type
aplication/json
{
  • "data": [
    ]
}

Get a Zarr collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Responses

Response Schema: application/json
object <ZarrCollection> (ZarrCollection)

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Zarr collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>
Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete Zarr collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Reingest a Zarr collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Responses

Response Schema: application/json
object <ZarrCollection> (ZarrCollection)

Response samples

Content type
application/json
{
  • "data": {
    }
}

Arrays

Query Zarr collection's arrays

path Parameters
collectionId
required
string <uuid>
query Parameters
count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

search
string

Optional query to search arrays by name. If omitted, all items are returned.

Responses

Response Schema: application/json
Array of objects <ZarrArray> (ZarrArray) [ items <ZarrArray > ]

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a single Zarr array

path Parameters
collectionId
required
string <uuid>
arrayName
required
string

Responses

Response Schema: application/json
object <ZarrArray> (ZarrArray)

Response samples

Content type
application/json
{
  • "data": {
    }
}

Search data

Search data with Process API-like interface.

Authorizations:
OAuth2
query Parameters
count
integer <int32> >= 1

Number of items to retrieve.

Maximum value is provider dependent.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

Request Body schema: application/json
One of
provider
required
string
Value: "AIRBUS"

Specify this value to use data provider Airbus OneAtlas.

required
object (ProcessRequestInputBounds)

Defines the request bounds by specifying the bounding box and/or geometry for the request. If both are given, a request is made for a geometry and bbox is ignored.

required
Array of objects = 1 items

Responses

Response Schema: application/json
One of
object (View)

Links to paginate the resource

features
<other fields>
any

Other fields returned by Airbus OneAtlas search may be included in the response.

Request samples

Content type
application/json
Example
{
  • "provider": "AIRBUS",
  • "bounds": {
    },
  • "data": [
    ]
}

Response samples

Content type
application/json
Example
{}

Native search

Proxy search. All the fields not listed as required are passed verbatim to the data provider's search API, and the result from the latter is returned verbatim.

Authorizations:
OAuth2
Request Body schema: application/json
One of
provider
required
string
Value: "AIRBUS"

Specify this value to use data provider Airbus OneAtlas.

property name*
additional property

Responses

Response Schema: application/json
One of
object (View)

Links to paginate the resource

features
<other fields>
any

Other fields returned by Airbus OneAtlas search may be included in the response.

Request samples

Content type
application/json
Example
{
  • "provider": "AIRBUS",
  • "geometry": {
    },
  • "constellation": "PHR",
  • "processingLevel": "SENSOR",
  • "acquisitionDate": "[2018-06-01T00:00:00.000Z,2018-09-01T00:00:00.000Z]",
  • "cloudCover": "[0,30]",
  • "snowCover": "[0,10]",
  • "incidenceAngle": "[0,10]"
}

Response samples

Content type
application/json
Example
{}

Product

Get thumbnail of data product

Get a scaled-down, non-geolocated, non-clipped image of the data product

Authorizations:
OAuth2
path Parameters
collectionId
required
string
Enum: "AIRBUS_PLEIADES" "AIRBUS_SPOT" "PLANET_SCOPE" "PLANET_SKYSAT" "MAXAR_WORLDVIEW"

Collection ID

productId
required
string

ID of the product to get thumbnail of, typically returned by a previous search

query Parameters
planetApiKey
string

Your Planet API key. Get one from Planet https://www.planet.com. It is required in order to get thumbnails of Planet data products unless you purchased your Planet data plan through Sentinel Hub.

Responses

Order

Create an order

Create a non-confirmed data order object, equivalent to a quote. After creation you can review the contents of the order and its quota requirements, and then choose to confirm it or not.

Data can be ordered by specifying a query (all items matching the query will be ordered) or item IDs (the specified items will be ordered).

Authorizations:
OAuth2
Request Body schema: application/json
One of
name
string

Order name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

collectionId
string <uuid>

BYOC collection ID. If given at order creation, requested data is imported into referenced collection, which must be compatible with the data being ordered - that is, must either be empty or contain the same bands as the data being ordered.

If not given at order creation, a new BYOC collection is created when the order is confirmed and its ID is returned in the response from the confirm endpoint.

required
object (AirbusSearchQuery)

Specification of the ordered data

Responses

Response Schema: application/json
id
string <uuid>

Order ID

name
string

Order name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

accountId
string <uuid>

Account ID

userId
string <uuid>

User ID

collectionId
string <uuid>

BYOC collection ID. If given at order creation, requested data is imported into referenced collection, which must be compatible with the data being ordered - that is, must either be empty or contain the same bands as the data being ordered.

If not given at order creation, a new BYOC collection is created when the order is confirmed and its ID is returned in the response from the confirm endpoint.

status
string (OrderStatus)
Enum: "CREATED" "CANCELLED" "RUNNING" "DONE" "PARTIAL" "FAILED"

Order status

sqkm
number

Total size of the order in km2 or minimum order area, whichever is greater

input
object

Specification of the ordered data

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "input": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "status": "CREATED",
  • "sqkm": 0,
  • "input": { }
}

Query orders

Authorizations:
OAuth2
query Parameters
status
string (OrderStatus)
Enum: "CREATED" "CANCELLED" "RUNNING" "DONE" "PARTIAL" "FAILED"

Filter orders by status. Omit to get all orders.

collectionId
string <uuid>

Filter orders by collectionId. Omit to get all orders.

count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

search
string

Optional search query. Either a single word to search for or multiple words separated by the | (or) and & (and) operators. If omitted, all items are returned.

deleted
boolean
Default: false

If set to true the response will only return those orders that had been deleted by the user.

Responses

Response Schema: application/json
Array of objects (Order)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get an order

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

Responses

Response Schema: application/json
id
string <uuid>

Order ID

name
string

Order name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

accountId
string <uuid>

Account ID

userId
string <uuid>

User ID

collectionId
string <uuid>

BYOC collection ID. If given at order creation, requested data is imported into referenced collection, which must be compatible with the data being ordered - that is, must either be empty or contain the same bands as the data being ordered.

If not given at order creation, a new BYOC collection is created when the order is confirmed and its ID is returned in the response from the confirm endpoint.

status
string (OrderStatus)
Enum: "CREATED" "CANCELLED" "RUNNING" "DONE" "PARTIAL" "FAILED"

Order status

sqkm
number

Total size of the order in km2 or minimum order area, whichever is greater

input
object

Specification of the ordered data

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "status": "CREATED",
  • "sqkm": 0,
  • "input": { }
}

Delete an order

CREATED orders will be permanently deleted.

CANCELLED , DONE or FAILED ones will be deleted for normal querying but will still be available.

PARTIAL or RUNNING orders cannot be deleted.

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Confirm an order

Confirm the order and start executing it. Requires sufficient quota for the order. Only orders with status CREATED can be confirmed.

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

Responses

Response Schema: application/json
id
string <uuid>

Order ID

name
string

Order name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

accountId
string <uuid>

Account ID

userId
string <uuid>

User ID

collectionId
string <uuid>

BYOC collection ID. If given at order creation, requested data is imported into referenced collection, which must be compatible with the data being ordered - that is, must either be empty or contain the same bands as the data being ordered.

If not given at order creation, a new BYOC collection is created when the order is confirmed and its ID is returned in the response from the confirm endpoint.

status
string (OrderStatus)
Enum: "CREATED" "CANCELLED" "RUNNING" "DONE" "PARTIAL" "FAILED"

Order status

sqkm
number

Total size of the order in km2 or minimum order area, whichever is greater

input
object

Specification of the ordered data

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "status": "CREATED",
  • "sqkm": 0,
  • "input": { }
}

Order delivery

Get order deliveries

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

query Parameters
status
string (DeliveryStatus)
Enum: "WAITING" "DELIVERED" "DELIVERY_FAILED" "PREPARING" "INGESTING" "DONE" "IMPORT_FAILED" "NON_INGESTIBLE"

Filter deliveries by status. Omit to get all deliveries.

count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

Responses

Response Schema: application/json
Array of OrderAirbusDelivery (object) or OrderPlanetDelivery (object) or OrderMaxarDelivery (object) (OrderDelivery)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get an order delivery

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

Responses

Response Schema: application/json
One of
provider
string
Value: "AIRBUS"

Provider of the delivery

id
string <uuid>

Delivery ID

sqkm
number

Size of the delivery in km2.

status
string (DeliveryStatus)
Enum: "WAITING" "DELIVERED" "DELIVERY_FAILED" "PREPARING" "INGESTING" "DONE" "IMPORT_FAILED" "NON_INGESTIBLE"

Delivery status

errorMessage
string

Error message if status = "DELIVERY_FAILED", "NON_INGESTIBLE" or "IMPORT_FAILED".

productId
string <uuid>

Airbus Product ID.

Response samples

Content type
application/json
Example
{
  • "provider": "AIRBUS",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "sqkm": 0,
  • "status": "WAITING",
  • "errorMessage": "string",
  • "productId": "dcd53ddb-8104-4e48-8cc0-5df1088c6113"
}

List files of an order delivery

Lists all files delivered by the data provider. The file list and contents is provider-specific.

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

Responses

Response Schema: application/json
Array
string <filename with path>

Response samples

Content type
application/json
[
  • "VOL_PHR.XML",
  • "INDEX.HTM",
  • "IMG_PHR1A_P_001/IMG_PHR1A_P_202102240924289_ORT_15c5eeb9-53a1-4cdd-cca6-d265fb1bf0c6-001_R1C1.J2W",
  • "..."
]

Retrieve a delivery file

Download a single file delivered by the data provider.

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

file
required
string

File with full path as returned by the "List delivery files" endpoint.

header Parameters
Range
string <RFC 7223>
Example: bytes=16384-23473

Optional byte range to retrieve part of a file according to RFC 7233. Typically used with large files to resume interrupted downloads.

Responses

Response Schema: application/octet-stream
string <binary> (file contents as delivered by data provider)

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get delivery file size

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

file
required
string

File with full path as returned by the "List delivery files" endpoint.

Responses

Response Headers
Content-Length
integer

File length in bytes

Response samples

Content type
application/json
{
  • "error": {
    }
}

Request creation of delivery archive

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

query Parameters
format
string (DeliveryArchiveFormat)
Default: "zip"
Value: "zip"

One of supported archive formats. Currently only zip is supported.

Responses

Response Schema: application/json
deliveryId
string <uuid>
format
string (DeliveryArchiveFormat)
Value: "zip"

One of supported archive formats. Currently only zip is supported.

requested
string <date-time>

Time of archiving request in ISO 8601

status
string (DeliveryArchiveStatus)
Enum: "WAITING" "PREPARING" "DONE" "FAILED"

Status of archive creation. Only archives with status DONE can be downloaded.

size
integer

Size of archive in bytes. Only provided for archives with status DONE.

Response samples

Content type
application/json
{
  • "deliveryId": "73dc828d-801d-4d29-b7e4-e046662a5901",
  • "format": "zip",
  • "requested": "2019-08-24T14:15:22Z",
  • "status": "WAITING",
  • "size": 0
}

Retrieve delivery archive

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

query Parameters
format
string (DeliveryArchiveFormat)
Default: "zip"
Value: "zip"

One of supported archive formats. Currently only zip is supported.

header Parameters
Range
string <RFC 7223>
Example: bytes=16384-23473

Optional byte range to retrieve part of the archive according to RFC 7233. Typically used to resume interrupted downloads.

Responses

Response Schema: application/octet-stream
string <binary> (archive contents)

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get size of delivery archive

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

query Parameters
format
string (DeliveryArchiveFormat)
Default: "zip"
Value: "zip"

One of supported archive formats. Currently only zip is supported.

Responses

Response Headers
Content-Length
integer

Archive length in bytes

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get status of delivery archive creation

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

query Parameters
format
string (DeliveryArchiveFormat)
Default: "zip"
Value: "zip"

One of supported archive formats. Currently only zip is supported.

Responses

Response Schema: application/json
deliveryId
string <uuid>
format
string (DeliveryArchiveFormat)
Value: "zip"

One of supported archive formats. Currently only zip is supported.

requested
string <date-time>

Time of archiving request in ISO 8601

status
string (DeliveryArchiveStatus)
Enum: "WAITING" "PREPARING" "DONE" "FAILED"

Status of archive creation. Only archives with status DONE can be downloaded.

size
integer

Size of archive in bytes. Only provided for archives with status DONE.

Response samples

Content type
application/json
{
  • "deliveryId": "73dc828d-801d-4d29-b7e4-e046662a5901",
  • "format": "zip",
  • "requested": "2019-08-24T14:15:22Z",
  • "status": "WAITING",
  • "size": 0
}

Order delivery tile

Get the tiles of an order delivery

The delivery tiles correspond to BYOC tiles that were created during the ingestion of this delivery. Thus their corresponding IDs will match. While for most deliveries just one tile is created, for the largest ones there can be tens of tiles.

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

Responses

Response Schema: application/json
Array of objects (DeliveryTile)

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get an order delivery tile

Authorizations:
OAuth2
path Parameters
orderId
required
string <uuid>

Order ID

deliveryId
required
string <uuid>

Delivery ID

tileId
required
string <uuid>

Tile ID

Responses

Response Schema: application/json
id
string <uuid>

Tile ID

deliveryId
string <uuid>

Tile ID

status
string (TileStatus)
Enum: "WAITING" "QUEUED" "INGESTING" "INGESTED" "FAILED"

The status of the tile.

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deliveryId": "73dc828d-801d-4d29-b7e4-e046662a5901",
  • "status": "WAITING"
}

Subscription

Create a subscription

Create a non-confirmed data subscription object. After creation you can review the parameters of the subscription and then choose to confirm it or not.

Authorizations:
OAuth2
Request Body schema: application/json
One of
name
string

Subscription name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

collectionId
string <uuid>

BYOC collection ID. If given at subscription creation, the data is imported into referenced collection, which must be compatible with the data being subscribed - that is, must either be empty or contain the same bands as the data being subscribed.

If not given at subscription creation, a new BYOC collection is created when the subscription is confirmed and its ID is returned in the response from the confirm endpoint.

required
object

Specification of the subscribed data

Responses

Response Schema: application/json
id
string <uuid>

Subscription ID

name
string

Subscription name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

accountId
string <uuid>

Account ID

userId
string <uuid>

User ID

collectionId
string <uuid>

BYOC collection ID. If given at subscription creation, the data is imported into referenced collection, which must be compatible with the data being subscribed - that is, must either be empty or contain the same bands as the data being subscribed.

If not given at subscription creation, a new BYOC collection is created when the subscription is confirmed and its ID is returned in the response from the confirm endpoint.

status
string (SubscriptionStatus)
Enum: "CREATED" "RUNNING" "CANCELLED" "COMPLETED" "FAILED"

Subscription status

sqkm
number

Area of the subscriptions's input.bounds in km2

input
object

Specification of the subscribed data

Request samples

Content type
application/json
{
  • "name": "string",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "input": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "status": "CREATED",
  • "sqkm": 0,
  • "input": { }
}

Query subscriptions

Authorizations:
OAuth2
query Parameters
status
string (SubscriptionStatus)
Enum: "CREATED" "RUNNING" "CANCELLED" "COMPLETED" "FAILED"

Filter subscriptions by status. Omit to get all subscriptions.

collectionId
string <uuid>

Filter subscriptions by collectionId. Omit to get all subscriptions.

count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

search
string

Optional search query. Either a single word to search for or multiple words separated by the | (or) and & (and) operators. If omitted, all items are returned.

deleted
boolean
Default: false

If set to true the response will only return those subscriptions that had been deleted by the user.

Responses

Response Schema: application/json
Array of objects (Subscription)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get a subscription

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

Responses

Response Schema: application/json
id
string <uuid>

Subscription ID

name
string

Subscription name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

accountId
string <uuid>

Account ID

userId
string <uuid>

User ID

collectionId
string <uuid>

BYOC collection ID. If given at subscription creation, the data is imported into referenced collection, which must be compatible with the data being subscribed - that is, must either be empty or contain the same bands as the data being subscribed.

If not given at subscription creation, a new BYOC collection is created when the subscription is confirmed and its ID is returned in the response from the confirm endpoint.

status
string (SubscriptionStatus)
Enum: "CREATED" "RUNNING" "CANCELLED" "COMPLETED" "FAILED"

Subscription status

sqkm
number

Area of the subscriptions's input.bounds in km2

input
object

Specification of the subscribed data

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "status": "CREATED",
  • "sqkm": 0,
  • "input": { }
}

Delete a non-running subscription

CREATED subscriptions will be permanently deleted.

CANCELLED , COMPLETED or FAILED ones will be deleted for normal querying but will still be available.

RUNNING subscriptions cannot be deleted.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Confirm a subscription

Confirm the subscription and start executing it. Only subscription with status CREATED can be confirmed.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

Responses

Response Schema: application/json
id
string <uuid>

Subscription ID

name
string

Subscription name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

accountId
string <uuid>

Account ID

userId
string <uuid>

User ID

collectionId
string <uuid>

BYOC collection ID. If given at subscription creation, the data is imported into referenced collection, which must be compatible with the data being subscribed - that is, must either be empty or contain the same bands as the data being subscribed.

If not given at subscription creation, a new BYOC collection is created when the subscription is confirmed and its ID is returned in the response from the confirm endpoint.

status
string (SubscriptionStatus)
Enum: "CREATED" "RUNNING" "CANCELLED" "COMPLETED" "FAILED"

Subscription status

sqkm
number

Area of the subscriptions's input.bounds in km2

input
object

Specification of the subscribed data

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "status": "CREATED",
  • "sqkm": 0,
  • "input": { }
}

Cancel a subscription

Cancel a RUNNING subscription so that it will stop executing. Already imported data will be kept. Only subscription with status RUNNING can be cancelled.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

Responses

Response Schema: application/json
id
string <uuid>

Subscription ID

name
string

Subscription name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.

accountId
string <uuid>

Account ID

userId
string <uuid>

User ID

collectionId
string <uuid>

BYOC collection ID. If given at subscription creation, the data is imported into referenced collection, which must be compatible with the data being subscribed - that is, must either be empty or contain the same bands as the data being subscribed.

If not given at subscription creation, a new BYOC collection is created when the subscription is confirmed and its ID is returned in the response from the confirm endpoint.

status
string (SubscriptionStatus)
Enum: "CREATED" "RUNNING" "CANCELLED" "COMPLETED" "FAILED"

Subscription status

sqkm
number

Area of the subscriptions's input.bounds in km2

input
object

Specification of the subscribed data

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "status": "CREATED",
  • "sqkm": 0,
  • "input": { }
}

Subscription delivery

Get subscription deliveries

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

query Parameters
status
string (DeliveryStatus)
Enum: "WAITING" "DELIVERED" "DELIVERY_FAILED" "PREPARING" "INGESTING" "DONE" "IMPORT_FAILED" "NON_INGESTIBLE"

Filter deliveries by status. Omit to get all deliveries.

count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

Responses

Response Schema: application/json
Array of SubscriptionPlanetDelivery (object) (SubscriptionDelivery)
object (View)

Links to paginate the resource

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {}
}

Get a subscription delivery

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

Responses

Response Schema: application/json
One of
provider
string
Value: "PLANET"

Provider of the delivery

id
string <uuid>

Delivery ID

status
string (DeliveryStatus)
Enum: "WAITING" "DELIVERED" "DELIVERY_FAILED" "PREPARING" "INGESTING" "DONE" "IMPORT_FAILED" "NON_INGESTIBLE"

Delivery status

errorMessage
string

Error message if status = "DELIVERY_FAILED", "NON_INGESTIBLE" or "IMPORT_FAILED".

itemId
string

Planet's item ID for PlanetScope and SkySat deliveries.

Response samples

Content type
application/json
{
  • "provider": "PLANET",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "WAITING",
  • "errorMessage": "string",
  • "itemId": "string"
}

List files of a subscription delivery

Lists all files delivered by the data provider. The file list and contents is provider-specific.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

Responses

Response Schema: application/json
Array
string <filename with path>

Response samples

Content type
application/json
[
  • "20211208_095127_54_2416_3B_AnalyticMS_SR_clip.tif",
  • "20211208_095127_54_2416_metadata.json",
  • "20211208_095127_54_2416_3B_AnalyticMS_metadata_clip.xml",
  • "20211208_095127_54_2416_3B_udm2_clip.tif"
]

Retrieve a delivery file

Download a single file delivered by the data provider.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

file
required
string

File with full path as returned by the "List delivery files" endpoint.

header Parameters
Range
string <RFC 7223>
Example: bytes=16384-23473

Optional byte range to retrieve part of a file according to RFC 7233. Typically used with large files to resume interrupted downloads.

Responses

Response Schema: application/octet-stream
string <binary> (file contents as delivered by data provider)

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get delivery file size

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

file
required
string

File with full path as returned by the "List delivery files" endpoint.

Responses

Response Headers
Content-Length
integer

File length in bytes

Response samples

Content type
application/json
{
  • "error": {
    }
}

Request creation of delivery archive

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

query Parameters
format
string (DeliveryArchiveFormat)
Default: "zip"
Value: "zip"

One of supported archive formats. Currently only zip is supported.

Responses

Response Schema: application/json
deliveryId
string <uuid>
format
string (DeliveryArchiveFormat)
Value: "zip"

One of supported archive formats. Currently only zip is supported.

requested
string <date-time>

Time of archiving request in ISO 8601

status
string (DeliveryArchiveStatus)
Enum: "WAITING" "PREPARING" "DONE" "FAILED"

Status of archive creation. Only archives with status DONE can be downloaded.

size
integer

Size of archive in bytes. Only provided for archives with status DONE.

Response samples

Content type
application/json
{
  • "deliveryId": "73dc828d-801d-4d29-b7e4-e046662a5901",
  • "format": "zip",
  • "requested": "2019-08-24T14:15:22Z",
  • "status": "WAITING",
  • "size": 0
}

Retrieve delivery archive

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

query Parameters
format
string (DeliveryArchiveFormat)
Default: "zip"
Value: "zip"

One of supported archive formats. Currently only zip is supported.

header Parameters
Range
string <RFC 7223>
Example: bytes=16384-23473

Optional byte range to retrieve part of the archive according to RFC 7233. Typically used to resume interrupted downloads.

Responses

Response Schema: application/octet-stream
string <binary> (archive contents)

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get size of delivery archive

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

query Parameters
format
string (DeliveryArchiveFormat)
Default: "zip"
Value: "zip"

One of supported archive formats. Currently only zip is supported.

Responses

Response Headers
Content-Length
integer

Archive length in bytes

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get status of delivery archive creation

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

query Parameters
format
string (DeliveryArchiveFormat)
Default: "zip"
Value: "zip"

One of supported archive formats. Currently only zip is supported.

Responses

Response Schema: application/json
deliveryId
string <uuid>
format
string (DeliveryArchiveFormat)
Value: "zip"

One of supported archive formats. Currently only zip is supported.

requested
string <date-time>

Time of archiving request in ISO 8601

status
string (DeliveryArchiveStatus)
Enum: "WAITING" "PREPARING" "DONE" "FAILED"

Status of archive creation. Only archives with status DONE can be downloaded.

size
integer

Size of archive in bytes. Only provided for archives with status DONE.

Response samples

Content type
application/json
{
  • "deliveryId": "73dc828d-801d-4d29-b7e4-e046662a5901",
  • "format": "zip",
  • "requested": "2019-08-24T14:15:22Z",
  • "status": "WAITING",
  • "size": 0
}

Subscription delivery tile

Get the tiles of a subscription delivery

The delivery tiles correspond to BYOC tiles that were created during the ingestion of this delivery. Thus their corresponding IDs will match. While for most deliveries just one tile is created, for the largest ones there can be tens of tiles.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

Responses

Response Schema: application/json
Array of objects (DeliveryTile)

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a subscription delivery tile

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string <uuid>

Subscription ID

deliveryId
required
string <uuid>

Delivery ID

tileId
required
string <uuid>

Tile ID

Responses

Response Schema: application/json
id
string <uuid>

Tile ID

deliveryId
string <uuid>

Tile ID

status
string (TileStatus)
Enum: "WAITING" "QUEUED" "INGESTING" "INGESTED" "FAILED"

The status of the tile.

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deliveryId": "73dc828d-801d-4d29-b7e4-e046662a5901",
  • "status": "WAITING"
}

Quota

Quotas are managed centrally at the main Sentinel Hub deployment, thus the quota API is only available at the https://services.sentinel-hub.com endpoint.

Get import quotas

Get the list of your import quotas for all providers and collections

Authorizations:
OAuth2

Responses

Response Schema: application/json
Array of objects (Quota)

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get import quota

Get the import quota for the specified collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string
Enum: "AIRBUS_PLEIADES" "AIRBUS_SPOT" "PLANET_SCOPE" "PLANET_SKYSAT" "MAXAR_WORLDVIEW"

Collection ID

Responses

Response Schema: application/json
collectionId
string (TpdiCollectionId)
Enum: "AIRBUS_PLEIADES" "AIRBUS_SPOT" "PLANET_SCOPE" "PLANET_SKYSAT" "MAXAR_WORLDVIEW"

Collection ID

quotaSqkm
number

This is total purchased quota. Available quota is quotaSqkm - quotaUsed.

quotaUsed
number

Quota used in square kilometers. Note that for PlanetScope's Hectares under Management pricing model this field does not apply and may contain arbitrary values.

Response samples

Content type
application/json
{
  • "collectionId": "AIRBUS_PLEIADES",
  • "quotaSqkm": 0,
  • "quotaUsed": 0
}

Data product

Search data product

Authorizations:
OAuth2
path Parameters
datasetType
required
string (DatasetType)
Enum: "sentinel-2-l1c" "sentinel-2-l2a" "landsat-8-l1c" "landsat-ot-l1" "landsat-ot-l2" "landsat-tm-l1" "landsat-tm-l2" "dem" "modis" "sentinel-1-grd" "s2gm" "sentinel-3-olci" "sentinel-3-slstr" "sentinel-5p-l2" "custom"

Dataset type

query Parameters
search
string

Optional search query. Either a single word to search for or multiple words separated by the | (or) and & (and) operators. If omitted, all items are returned.

count
integer <int32>

Upper limit to the number of items to retrieve. It cannot be larger than the endpoint-specific limit. If omitted, the endpoint-specific limit is used. For more records, use viewtoken to page through.

viewtoken
string

When total number of items is larger than count, the response contains viewtoken. This viewtoken can be used in the next request to retrieve the next page of items.

sort
string

sort

Responses

Response Schema: application/json
Array
@id
string

Resource URL reference to the data product.

id
integer <int64>

Identifier

name
string

Data product name.

description
string

A description of the data product.

evalScript
string

The evalscript of the data product.

object (ResourceReference)
baseProduct
string
visualization
string

Visualization type.

Note: Not present for every data product.

scriptVersion
integer

Evalscript version.

listed
boolean

If false the data product is deprecated.

Response samples

Content type
application/json
[
  • {
    }
]

Get data product

Get an existing data product

Authorizations:
OAuth2
path Parameters
datasetType
required
string (DatasetType)
Enum: "sentinel-2-l1c" "sentinel-2-l2a" "landsat-8-l1c" "landsat-ot-l1" "landsat-ot-l2" "landsat-tm-l1" "landsat-tm-l2" "dem" "modis" "sentinel-1-grd" "s2gm" "sentinel-3-olci" "sentinel-3-slstr" "sentinel-5p-l2" "custom"

Dataset type

id
required
integer <int64>

Dataproduct ID

Responses

Response Schema: application/json
@id
string

Resource URL reference to the data product.

id
integer <int64>

Identifier

name
string

Data product name.

description
string

A description of the data product.

evalScript
string

The evalscript of the data product.

object (ResourceReference)
baseProduct
string
visualization
string

Visualization type.

Note: Not present for every data product.

scriptVersion
integer

Evalscript version.

listed
boolean

If false the data product is deprecated.

Response samples

Content type
application/json
{
  • "@id": "string",
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "evalScript": "string",
  • "dataset": {
    },
  • "baseProduct": "string",
  • "visualization": "string",
  • "scriptVersion": 0,
  • "listed": true
}

Dataset

Get all datasets

Get all existing datasets

Authorizations:
OAuth2

Responses

Response Schema: application/json
Array
@id
string

Resource URL reference

id
string

Identifier

name
string

Response samples

Content type
application/json
[
  • {
    }
]

Get dataset

Get an existing dataset

Authorizations:
OAuth2
path Parameters
datasetType
required
string (DatasetType)
Enum: "sentinel-2-l1c" "sentinel-2-l2a" "landsat-8-l1c" "landsat-ot-l1" "landsat-ot-l2" "landsat-tm-l1" "landsat-tm-l2" "dem" "modis" "sentinel-1-grd" "s2gm" "sentinel-3-olci" "sentinel-3-slstr" "sentinel-5p-l2" "custom"

Dataset type

Responses

Response Schema: application/json
@id
string

Resource URL reference

id
string

Identifier

name
string

Response samples

Content type
application/json
{
  • "@id": "string",
  • "id": "string",
  • "name": "string"
}

Dataset source

Get dataset sources

Get all existing dataset sources

Authorizations:
OAuth2
path Parameters
datasetId
required
string

Dataset ID

Responses

Response Schema: application/json
Array
id
integer <int64>

Identifier

description
string
object (Settings)
object (ResourceReference)

Response samples

Content type
application/json
[
  • {
    }
]

Get dataset source

Get an existing dataset source

Authorizations:
OAuth2
path Parameters
datasetId
required
string

Dataset ID

id
required
integer <int64>

Dataset source ID

Responses

Response Schema: application/json
id
integer <int64>

Identifier

description
string
object (Settings)
object (ResourceReference)

Response samples

Content type
application/json
{
  • "id": 0,
  • "description": "string",
  • "settings": {
    },
  • "dataset": {
    }
}

Instance user data

Get instance user data

Get an existing WMS instance user data

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Responses

Response Schema: application/json
id
string <uuid>

Identifier

user_data
object
object (ResolvableWmsInstance)

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_data": { },
  • "instance": {
    }
}

Update instance user data

Update an existing WMS instance user data

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Request Body schema: application/json
user_data
object

Responses

Request samples

Content type
application/json
{
  • "user_data": { }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Create instance user data

Create a new WMS instance user data

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Request Body schema: application/json
user_data
object

Responses

Response Schema: application/json
id
string <uuid>

Identifier

user_data
object
object (ResolvableWmsInstance)

Request samples

Content type
application/json
{
  • "user_data": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_data": { },
  • "instance": {
    }
}

Delete instance user data

Delete an existing WMS instance user data

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Layer user data

Get layer user data

Get an existing WMS layer user data

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

layerId
required
string

Layer ID

Responses

Response Schema: application/json
id
string

Identifier

user_data
object
object (ResolvableWmsLayer)
object (ResolvableWmsInstance)

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_data": { },
  • "layer": {
    },
  • "instance": {
    }
}

Update layer user data

Update an existing layer user data

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

layerId
required
string

Layer ID

Request Body schema: application/json
user_data
object

Responses

Request samples

Content type
application/json
{
  • "user_data": { }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Create layer user data

Create a new WMS layer user data

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

layerId
required
string

Layer ID

Request Body schema: application/json
user_data
object

Responses

Response Schema: application/json
id
string

Identifier

user_data
object
object (ResolvableWmsLayer)
object (ResolvableWmsInstance)

Request samples

Content type
application/json
{
  • "user_data": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_data": { },
  • "layer": {
    },
  • "instance": {
    }
}

Delete layer user data

Delete an existing WMS layer user data

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

layerId
required
string

Layer ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Layer

Get layers

Get all WMS layers for a WMS instance

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Responses

Response Schema: application/json
Array
id
string

Identifier

title
string
description
string
Array of objects (WmsLayerStyle)
orderHint
integer <int32>
object (ResolvableWmsInstance)
lastUpdated
string

The date when the instance was last updated.

object (ResourceReference)
object (ResolvableDatasetSourceDescriptor)
defaultStyleName
string
object (WmsLayerDatasourceAttributes)
object (WmsLayerAdditionalData)

Response samples

Content type
application/json
[
  • {
    }
]

Create layer

Create a new WMS layer

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Request Body schema: application/json
id
string

Identifier

title
string
description
string
Array of objects (WmsLayerStyle)
orderHint
integer <int32>
object (ResolvableWmsInstance)
object (ResourceReference)
object (ResolvableDatasetSourceDescriptor)
defaultStyleName
string
object (WmsLayerDatasourceAttributes)
object (WmsLayerAdditionalData)

Responses

Response Schema: application/json
id
string

Identifier

title
string
description
string
Array of objects (WmsLayerStyle)
orderHint
integer <int32>
object (ResolvableWmsInstance)
lastUpdated
string

The date when the instance was last updated.

object (ResourceReference)
object (ResolvableDatasetSourceDescriptor)
defaultStyleName
string
object (WmsLayerDatasourceAttributes)
object (WmsLayerAdditionalData)

Request samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "styles": [
    ],
  • "orderHint": 0,
  • "instance": {
    },
  • "dataset": {
    },
  • "datasetSource": {
    },
  • "defaultStyleName": "string",
  • "datasourceDefaults": {
    },
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "styles": [
    ],
  • "orderHint": 0,
  • "instance": {
    },
  • "lastUpdated": "string",
  • "dataset": {
    },
  • "datasetSource": {
    },
  • "defaultStyleName": "string",
  • "datasourceDefaults": {
    },
  • "additionalData": {
    }
}

Get layer

Get an existing WMS layer

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

layerId
required
string

Layer ID

query Parameters
expand
boolean
Default: false

Add styles to response

Responses

Response Schema: application/json
id
string

Identifier

title
string
description
string
Array of objects (WmsLayerStyle)
orderHint
integer <int32>
object (ResolvableWmsInstance)
lastUpdated
string

The date when the instance was last updated.

object (ResourceReference)
object (ResolvableDatasetSourceDescriptor)
defaultStyleName
string
object (WmsLayerDatasourceAttributes)
object (WmsLayerAdditionalData)

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "styles": [
    ],
  • "orderHint": 0,
  • "instance": {
    },
  • "lastUpdated": "string",
  • "dataset": {
    },
  • "datasetSource": {
    },
  • "defaultStyleName": "string",
  • "datasourceDefaults": {
    },
  • "additionalData": {
    }
}

Update layer

Update an existing WMS layer

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

layerId
required
string

Layer ID

Request Body schema: application/json
id
string

Identifier

title
string
description
string
Array of objects (WmsLayerStyle)
orderHint
integer <int32>
object (ResolvableWmsInstance)
object (ResourceReference)
object (ResolvableDatasetSourceDescriptor)
defaultStyleName
string
object (WmsLayerDatasourceAttributes)
object (WmsLayerAdditionalData)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "styles": [
    ],
  • "orderHint": 0,
  • "instance": {
    },
  • "dataset": {
    },
  • "datasetSource": {
    },
  • "defaultStyleName": "string",
  • "datasourceDefaults": {
    },
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete layer

Delete an existing WMS layer

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

layerId
required
string

Layer ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Instance

Get instances

Returns user's WMS instances

Authorizations:
OAuth2

Responses

Response Schema: application/json
Array
id
string <uuid>

Identifier

name
string
description
string
object or object (Geometry)
userId
string <uuid>
created
string

The date when the instance was created.

lastUpdated
string

The date when the instance was last updated.

object (WmsInstanceAdditionalData)
object (ResolvableCollectionWmsLayer)

Response samples

Content type
application/json
[
  • {
    }
]

Create instance

Create a new WMS instance

Authorizations:
OAuth2
Request Body schema: application/json
id
string <uuid>

Identifier

name
string
description
string
object or object (Geometry)
userId
string <uuid>
object (WmsInstanceAdditionalData)
object (ResolvableCollectionWmsLayer)

Responses

Response Schema: application/json
id
string <uuid>

Identifier

name
string
description
string
object or object (Geometry)
userId
string <uuid>
created
string

The date when the instance was created.

lastUpdated
string

The date when the instance was last updated.

object (WmsInstanceAdditionalData)
object (ResolvableCollectionWmsLayer)

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "areaOfInterest": {
    },
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "additionalData": {
    },
  • "layers": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "areaOfInterest": {
    },
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "created": "string",
  • "lastUpdated": "string",
  • "additionalData": {
    },
  • "layers": {
    }
}

Get instance

Get an existing WMS instance

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Responses

Response Schema: application/json
id
string <uuid>

Identifier

name
string
description
string
object or object (Geometry)
userId
string <uuid>
created
string

The date when the instance was created.

lastUpdated
string

The date when the instance was last updated.

object (WmsInstanceAdditionalData)
object (ResolvableCollectionWmsLayer)

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "areaOfInterest": {
    },
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "created": "string",
  • "lastUpdated": "string",
  • "additionalData": {
    },
  • "layers": {
    }
}

Update instance

Update an existing WMS instance

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Request Body schema: application/json
id
string <uuid>

Identifier

name
string
description
string
object or object (Geometry)
userId
string <uuid>
object (WmsInstanceAdditionalData)
object (ResolvableCollectionWmsLayer)

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "areaOfInterest": {
    },
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "additionalData": {
    },
  • "layers": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete instance

Delete an existing WMS instance

Authorizations:
OAuth2
path Parameters
instanceId
required
string <uuid>

Instance ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Location

List all locations

List all available Sentinel Hub deployment locations including their metadata

Authorizations:
OAuth2

Responses

Response Schema: application/json
Array
@id
string <uri>
id
string

Sentinel Hub deployment location identifier

url
string

Endpoint url

wmsUrl
string

WMS Service url

processUrl
string

Process API url

catalogUrl
string

Catalog API url

Response samples

Content type
application/json
[
  • {
    }
]

Speficic Location

Metadata on specific deployment location

Authorizations:
OAuth2
path Parameters
locationId
required
string

Sentinel Hub deployment location identifier

Responses

Response Schema: application/json
@id
string <uri>
id
string

Sentinel Hub deployment location identifier

url
string

Endpoint url

wmsUrl
string

WMS Service url

processUrl
string

Process API url

catalogUrl
string

Catalog API url

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "wmsUrl": "string",
  • "processUrl": "string",
  • "catalogUrl": "string"
}

Collection

BYOC Collection

Metadata about specific BYOC collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

BYOC Collection identifier

Responses

Response Schema: application/json
@id
string <uri>
id
string

BYOC Collection identifier

object (Location)

BYOC Collection location

datasetType
string (CustomDatasetType)
Value: "custom"
Array of objects (BandMetadata)

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "datasetType": "custom",
  • "bands": [
    ]
}

Batch Collection

Metadata about specific batch collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Batch Collection identifier

Responses

Response Schema: application/json
@id
string <uri>
id
string

Batch Collection identifier

object (Location)

Batch Collection location

datasetType
string (CustomDatasetType)
Value: "custom"
Array of objects (BandMetadata)

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "datasetType": "custom",
  • "bands": [
    ]
}

Zarr Collection

Metadata about specific Zarr collection

Authorizations:
OAuth2
path Parameters
collectionId
required
string <uuid>

Zarr Collection identifier

Responses

Response Schema: application/json
@id
string <uri>
id
string

Zarr Collection identifier

object (Location)

Zarr Collection location

datasetType
string (CustomDatasetType)
Value: "custom"
Array of objects (BandMetadata)

Response samples

Content type
application/json
{
  • "id": "string",
  • "location": {
    },
  • "datasetType": "custom",
  • "bands": [
    ]
}