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