openapi: 3.1.0
info:
title: API Reference async_process dataimport_order API
version: 1.0.0
contact:
name: Sentinel Hub
description: '**NOTE:** _Asynchronous Processing API is currently in beta release._
'
servers:
- url: https://services.sentinel-hub.com
tags:
- name: dataimport_order
x-displayName: Order
description: 'TPDI Service for Planet data is deprecated and will be sunset on November 11th, 2026. Please use [Planet Orders API](https://docs.planet.com/develop/apis/orders/reference/) instead.
'
paths:
/api/v1/dataimport/orders:
post:
summary: Create an order
description: '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).
'
operationId: dataImport_createOrder
tags:
- dataimport_order
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'200':
description: Order created
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
security:
- OAuth2: []
get:
summary: Query orders
operationId: dataImport_getOrders
tags:
- dataimport_order
parameters:
- $ref: '#/components/parameters/OrderStatus'
- name: collectionId
description: Filter orders by collectionId. Omit to get all orders.
in: query
schema:
type: string
format: uuid
- $ref: '#/components/parameters/SearchBeanCount'
- $ref: '#/components/parameters/SearchBeanViewtoken'
- $ref: '#/components/parameters/SearchBeanSearch'
- name: deleted
description: If set to `true` the response will only return those orders that had been deleted by the user.
in: query
schema:
default: false
type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Order'
links:
$ref: '#/components/schemas/View'
'401':
$ref: '#/components/responses/401'
security:
- OAuth2: []
/api/v1/dataimport/orders/{orderId}:
get:
summary: Get an order
operationId: dataImport_getOrder
tags:
- dataimport_order
parameters:
- $ref: '#/components/parameters/OrderId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
security:
- OAuth2: []
delete:
summary: Delete an order
operationId: dataImport_deleteOrder
description: "`CREATED` orders will be permanently deleted.\n\n `CANCELLED` , `DONE` or `FAILED` ones will be deleted for normal querying but will still be available.\n\n `PARTIAL` or `RUNNING` orders cannot be deleted."
tags:
- dataimport_order
parameters:
- $ref: '#/components/parameters/OrderId'
responses:
'204':
description: Successful response - order deleted
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
description: Conflict - order cannot be deleted because it is currently being processed.
security:
- OAuth2: []
/api/v1/dataimport/orders/{orderId}/confirm:
post:
summary: Confirm an order
description: 'Confirm the order and start executing it. Requires sufficient quota for the order. Only orders with status CREATED can be confirmed.
'
operationId: dataImport_confirmOrder
tags:
- dataimport_order
parameters:
- $ref: '#/components/parameters/OrderId'
responses:
'200':
description: Successful response - order confirmed
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'401':
$ref: '#/components/responses/401'
'403':
description: Insufficient quota for the order
content:
application/json:
schema:
$ref: '#/components/schemas/QuotaExceededError'
'409':
description: Conflict - order cannot be confirmed because its status is not CREATED.
security:
- OAuth2: []
components:
schemas:
ProcessRequestInputBounds:
title: Bounds
description: 'Defines the request bounds by specifying the bounding box and/or
geometry for the request. If both are specified it will generate an image
for the bounding box and render data contained within the geometry.
'
type: object
properties:
bbox:
description: 'The request bounding box. This and/or GEOMETRY must be specified.
Specify with a coordinate pair on two (opposite) vertices of the bounding
box rectangle. Coordinates need to be in easting,northing or longitude, latitude,
in that order in the CRS defined in the "bounds.properties.crs" parameter.
'
type: array
minItems: 4
maxItems: 4
items:
type: number
format: double
example:
- 13.822174072265625
- 45.85080395917834
- 14.55963134765625
- 46.29191774991382
geometry:
$ref: '#/components/schemas/Geometry'
properties:
$ref: '#/components/schemas/ProcessRequestInputBoundsProperties'
OrderRequest:
oneOf:
- $ref: '#/components/schemas/PlanetOrderRequest'
- $ref: '#/components/schemas/MaxarOrderRequest'
PlanetOrderRequest:
deprecated: true
allOf:
- $ref: '#/components/schemas/Order'
- type: object
required:
- input
properties:
input:
allOf:
- $ref: '#/components/schemas/PlanetOrderRequestBase'
- $ref: '#/components/schemas/PlanetSearchQuery'
- type: object
properties:
data:
type: array
description: 'To order specific Planet items, list their IDs in itemIds field. Otherwise, provide search criteria in the dataFilter field to order all items matching the criteria. Omitting both will order all items within the specified bounds.
In both cases, at most 500 items can be ordered at once, i.e. orders listing too many item IDs will fail, as will search-based orders that match too many items. Instead of larger search-based orders we recommend to use <a href="#tag/dataimport_subscription">subscriptions</a>.
'
items:
type: object
required:
- harmonizeTo
properties:
harmonizeTo:
type: string
enum:
- NONE
- Sentinel-2
description: 'Sensing instrument whose values the data should be harmonized to. Supported values:
* `NONE` to disable harmonization,
* `Sentinel-2` only for *PSScene* item type and surface reflectance product bundles,
'
externalDocs:
description: Details on PlanetScope instruments
url: https://developers.planet.com/docs/data/sensors/
itemIds:
type: array
minItems: 1
maxItems: 250
description: 'List of itemIds to order, if dataFilter is not provided. The itemId list is typically obtained from a previous search request.
'
items:
type: string
QuotaExceededError:
allOf:
- $ref: '#/components/schemas/Boom'
- type: object
properties:
errors:
type: object
properties:
availableQuota:
type: number
description: Currently available quota for the provider of the order
requiredQuota:
type: number
description: Quota that would be required for successful confirmation of the order
MaxarMaxOffNadir:
type: number
format: int
minimum: 0
maximum: 45
default: 45
RestErrorWrapper:
type: object
properties:
error:
$ref: '#/components/schemas/Boom'
PlanetOrderRequestBase:
deprecated: true
type: object
required:
- provider
- planetApiKey
properties:
provider:
description: Specify this value to use data provider Planet.
type: string
enum:
- PLANET
planetApiKey:
description: Your Planet API key. Get one from Planet https://www.planet.com.
type: string
PlanetSearchRequestBase:
deprecated: true
type: object
required:
- provider
properties:
provider:
description: Specify this value to use data provider Planet.
type: string
enum:
- PLANET
planetApiKey:
description: 'Your Planet API key. Get one from Planet https://www.planet.com.
It is required unless you purchased your Planet data plan through Sentinel Hub,
in which case it is optional and will filter search results based on the permissions of the key.
'
type: string
View:
description: Links to paginate the resource
type: object
properties:
currentToken:
type: string
nextToken:
type: string
previousToken:
type: string
'@id':
type: string
format: uri
next:
type: string
format: uri
previous:
type: string
format: uri
Polygon:
type: object
properties:
type:
type: string
enum:
- Polygon
coordinates:
type: array
items:
type: array
items:
maxItems: 2
minItems: 2
type: array
items:
type: number
format: double
ProcessRequestInputBoundsProperties:
title: BoundsProperties
type: object
properties:
crs:
description: 'The coordinate reference system of the coordinates. Must be
one of the values listed at https://docs.planet.com/develop/apis/processing/#crs-support.
Default CRS is WGS84, http://www.opengis.net/def/crs/OGC/1.3/CRS84.
'
type: string
default: http://www.opengis.net/def/crs/OGC/1.3/CRS84
MaxarMaxSunElevation:
description: The maximum allowable sun elevation in degrees
type: number
format: int
minimum: 0
maximum: 90
default: 90
MaxarSearchQuery:
allOf:
- $ref: '#/components/schemas/MaxarRequestBase'
- $ref: '#/components/schemas/SearchQueryBase'
- type: object
properties:
data:
type: array
minItems: 1
maxItems: 1
items:
type: object
required:
- productBands
properties:
productBands:
type: string
description: 'Band Bundle
'
enum:
- 4BB
dataFilter:
type: object
properties:
minOffNadir:
$ref: '#/components/schemas/MaxarMinOffNadir'
maxOffNadir:
$ref: '#/components/schemas/MaxarMaxOffNadir'
minSunElevation:
$ref: '#/components/schemas/MaxarMinSunElevation'
maxSunElevation:
$ref: '#/components/schemas/MaxarMaxSunElevation'
sensor:
$ref: '#/components/schemas/MaxarSensor'
MaxarSensor:
description: 'If specified, limits search results to a single sensor (satellite).
Results are also filtered to include only sensors that support the requested `productBands`. Thus, if a sensor that does not support all bands is specified, no results will be returned.
'
type: string
enum:
- WV01
- WV02
- WV03
- WV04
- GE01
MaxarMinOffNadir:
type: number
format: int
minimum: 0
maximum: 45
default: 0
OrderStatus:
description: Order status
type: string
readOnly: true
enum:
- CREATED
- CANCELLED
- RUNNING
- DONE
- PARTIAL
- FAILED
MaxCloudCoverage:
description: The maximum allowable cloud coverage in percent.
type: number
format: double
minimum: 0
maximum: 100
default: 100
PlanetSearchQuery:
deprecated: true
allOf:
- $ref: '#/components/schemas/PlanetSearchRequestBase'
- $ref: '#/components/schemas/SearchQueryBase'
- type: object
properties:
data:
type: array
minItems: 1
maxItems: 1
items:
type: object
required:
- itemType
- productBundle
properties:
type:
type: string
enum:
- catalog
default: catalog
description: 'Use `catalog` for PlanetScope and SkySat data.
'
itemType:
type: string
enum:
- PSScene
- SkySatCollect
description: 'The item type of data to search for or order:
* Use [PSScene](https://developers.planet.com/docs/data/psscene/) to order PlanetScope data.
[PSScene4Band](https://developers.planet.com/docs/data/psscene4band/) is deprecated and cannot be ordered since November 1st 2022.
* Use [SkySatCollect](https://developers.planet.com/docs/data/skysatcollect/) to order SkySat archive data.
'
externalDocs:
description: Item Types Documentation
url: https://developers.planet.com/docs/apis/data/items-assets/#item-types
productBundle:
type: string
enum:
- analytic_udm2
- analytic_sr_udm2
- analytic_8b_udm2
- analytic_8b_sr_udm2
- analytic
- analytic_sr
- panchromatic
description: 'When ordering, selects the product bundle (that is, the group of assets) to order.
When searching, limits search to products available as the specified product bundle.
Supported values depend on item type:
* for `PSScene`, the product bundles containing "*udm2*" are supported,
* for `SkySatCollect`, `analytic_udm2`, `analytic_sr_udm2` and `panchromatic` are supported.
Other values used by Planet but not listed here are not supported.
'
externalDocs:
description: Product Bundles Reference
url: https://developers.planet.com/apis/orders/product-bundles-reference/
dataFilter:
type: object
properties:
nativeFilter:
type: object
description: Planet Data API search filters
externalDocs:
description: Link to the Planet documentation page about search filters.
url: https://developers.planet.com/docs/data/searches-filtering/#search-filters
example:
type: RangeFilter
field_name: snow_ice_percent
config:
gte: 10
TimeRange:
type: object
description: A time interval to filter data by acquisition date. It is defined by a start and end date and time, e.g. 2019-01-31T14:00:00+01:00. A date representation without time (e.g. 2019-01-31) will not work. Both the start and end of a time interval are inclusive and can be equal.
properties:
from:
description: The start of a search interval.
type: string
format: date-time
to:
description: The end of a search interval.
type: string
format: date-time
example:
from: '2018-10-01T00:00:00.000Z'
to: '2018-11-01T00:00:00.000Z'
SearchQueryBase:
required:
- provider
- bounds
- data
properties:
provider:
type: string
bounds:
description: '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.
'
$ref: '#/components/schemas/ProcessRequestInputBounds'
data:
type: array
minItems: 1
maxItems: 1
items:
type: object
properties:
dataFilter:
type: object
properties:
timeRange:
$ref: '#/components/schemas/TimeRange'
maxCloudCoverage:
$ref: '#/components/schemas/MaxCloudCoverage'
MaxarMinSunElevation:
description: The minimum allowable sun elevation in degrees
type: number
format: int
minimum: 0
maximum: 90
default: 0
MaxarRequestBase:
type: object
required:
- provider
properties:
provider:
description: Specify this value to use data provider Maxar.
type: string
enum:
- MAXAR
Order:
type: object
properties:
id:
description: Order ID
type: string
format: uuid
readOnly: true
name:
description: Order name. It's also used as a name for a new BYOC collection, if no collection is given in collectionId field.
type: string
accountId:
description: Account ID
type: string
format: uuid
readOnly: true
collectionId:
description: '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.
'
type: string
format: uuid
status:
$ref: '#/components/schemas/OrderStatus'
sqkm:
description: Total size of the order in km<sup>2</sup> or minimum order area, whichever is greater
type: number
readOnly: true
input:
type: object
description: Specification of the ordered data
MultiPolygon:
type: object
properties:
type:
type: string
enum:
- MultiPolygon
coordinates:
type: array
items:
type: array
items:
type: array
items:
maxItems: 2
minItems: 2
type: array
items:
type: number
format: double
Boom:
type: object
properties:
status:
description: HTTP status code
type: integer
format: int32
reason:
description: Reason for the error
type: string
message:
description: Friendly error message
type: string
code:
description: Code that uniquely identifies the error
type: string
enum:
- COMMON_BAD_PAYLOAD
- COMMON_NOT_FOUND
- COMMON_DATABASE_ERROR
- COMMON_UNIQUE_KEY_VIOLATION
- COMMON_INSUFFICIENT_PERMISSIONS
- COMMON_SENTINEL_ACCOUNT_EXPIRED
- COMMON_METHOD_NOT_ALLOWED
- COMMON_UNSUPPORTED_MEDIA_TYPE
- COMMON_ELASTICSEARCH_ERROR
- COMMON_UNAUTHORIZED
- COMMON_EXCEPTION
- RATE_LIMIT_STORAGE_TIMEOUT
- RATE_LIMIT_OVERLAPPING_POLICIES
- RATE_LIMIT_EXCEEDED
- RATE_LIMIT_TOKEN_COUNT_EXCEEDS_CAPACITY
- DASHBOARD_PAYPAL_SALE_ERROR
- DASHBOARD_PAYPAL_SUBSCRIPTION_ERROR
- DASHBOARD_INVALID_PAYPAL_RESPONSE
- DASHBOARD_EXECUTE_SALE_ERROR
- DASHBOARD_EXECUTE_AGREEMENT_ERROR
- DASHBOARD_IPN_ERROR
- DASHBOARD_ADYEN_SALE_ERROR
- DASHBOARD_ADYEN_PAYMENT_CANCELLED
- RENDERER_EXCEPTION
- OAUTH_ERROR
- EMAIL_OCTOPUS_ERROR
errors:
description: Additional information about the error (Optional)
type: object
Geometry:
description: The request area of interest geometry. This and/or BBOX must be specified. Coordinates need to be in easting,northing or longitude,latitude, in that order in the CRS defined in the "bounds.properties.crs" parameter. A GeoJsonObject.
type: object
oneOf:
- $ref: '#/components/schemas/Polygon'
- $ref: '#/components/schemas/MultiPolygon'
example:
type: Polygon
coordinates:
- - - 14.000701904296873
- 46.23685258143992
- - 13.822174072265625
- 46.09037664604301
- - 14.113311767578125
- 45.85080395917834
- - 14.55963134765625
- 46.038922598236
- - 14.441528320312498
- 46.28717293114449
- - 14.17236328125
- 46.29191774991382
- - 14.000701904296873
- 46.23685258143992
MaxarOrderRequest:
allOf:
- $ref: '#/components/schemas/Order'
- type: object
required:
- input
properties:
input:
allOf:
- $ref: '#/components/schemas/MaxarSearchQuery'
- type: object
properties:
data:
type: array
description: 'To order specific MAXAR products, list them in the `selectedImages` field. Otherwise, provide search criteria in the dataFilter field to order all items matching the criteria.
In both cases, at most 10 products can be ordered at once, i.e. orders listing too many product IDs will fail, as will search-based orders that match too many products.
Minimum order of 5 km^2 applies to each product, i.e. if the intersection of order''s bounds and products''s bounds is smaller, the order will fail.
'
items:
type: object
properties:
productKernel:
type: string
default: CC
enum:
- CC
- NN
- MTF
description: 'Selects the resampling kernel to use: 4x4 cubic convolution (CC), nearest neighbour (NN), or the proprietary MTF kernel (MTF).
'
selectedImages:
type: array
minItems: 1
maxItems: 10
description: 'Only provide this field when ordering specific MAXAR products -- leave out when ordering via search criteria.
'
items:
type: string
description: The ID of product (strip) to order
parameters:
OrderId:
name: orderId
description: Order ID
in: path
required: true
schema:
type: string
format: uuid
SearchBeanViewtoken:
name: viewtoken
description: 'When the 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.
The next page can be retrieved by repeating the query. However, replace your URL with the
next URL in the returned links object.
'
in: query
schema:
type: string
SearchBeanCount:
name: count
description: '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.'
in: query
schema:
type: integer
format: int32
OrderStatus:
name: status
description: Filter orders by status. Omit to get all orders.
in: query
schema:
$ref: '#/components/schemas/OrderStatus'
SearchBeanSearch:
name: search
description: 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.
in: query
schema:
type: string
responses:
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/RestErrorWrapper'
'403':
description: Insufficient permissions
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/RestErrorWrapper'
'401':
description: Unauthorized
securitySchemes:
OAuth2:
type: oauth2
description: "### Authentication\n\nMore about the authentication <a href=\"https://docs.planet.com/develop/authentication/\" target=\"_blank\">here</a>.\n\nTo get an access token using curl:\n\n```\ncurl --request POST \\\n --url https://services.sentinel-hub.com/auth/realms/main/protocol/openid-connect/token \\\n --header \"content-type: application/x-www-form-urlencoded\" \\\n --data \"grant_type=client_credentials&client_id=<your client id>&client_secret=<your client secret>\"\n```\n"
flows:
clientCredentials:
tokenUrl: https://services.sentinel-hub.com/auth/realms/main/protocol/openid-connect/token
scopes:
SH: Sentinel Hub
x-tagGroups:
- name: Process API
tags:
- process
- name: Catalog
tags:
- catalog_core
- catalog_collections
- catalog_features
- catalog_item_search
- name: Async API
tags:
- async_process
- name: BatchV2 API
tags:
- batch_v2_process
- batch_v2_tiling_grid
- name: Stats API
tags:
- statistical
- name: Batch Stats API
tags:
- batch_statistical
- name: BYOC
tags:
- byoc_collection
- byoc_tile
- name: Zarr Import API
tags:
- zarr_collection
- zarr_array
- name: TPDI
tags:
- dataimport_search
- dataimport_product
- dataimport_order
- dataimport_delivery
- dataimport_tile_delivery
- dataimport_subscription
- dataimport_subscription_delivery
- dataimport_subscription_tile_delivery
- dataimport_quota
- name: Metadata
tags:
- metadata_location
- metadata_collection