Third Party Data Import API

The Third Party Data Import API (TPDI) enables you to import data offered by different data providers into Sentinel Hub (SH). The API allows you to search for available data and to order the import of selected data into Sentinel Hub. In Sentinel Hub, the data is stored in a BYOC collection and can be accessed using SH Process or SH OGC APIs.

Currently, we offer import for:

We are working on offering an import of other third party data.

To get to know the Third Party Data Import API, check out API reference and examples. Also, to get you started, we have prepared a step by step tutorial on ordering and visualizing commercial data using Postman.

Workflow

TPDI is very closely related to our BYOC service, since purchased third party data will be imported into BYOC collections and accessible through our Process or OGC API. We recommend not to mix different third party data types (e.g. PlanetScope, Pleiades, SPOT) and have one collection per kind.

Note that error codes and error messages are forwarded from data provider's APIs, therefore more information about these can be found in their documentation.

Searching data

The search API enables you to browse through the third party data archives. It is especially useful when you are not sure what data is available or which particular scenes you want to order. There are two different interfaces that can be used for searching. If you are not sure which one to use, we suggest you try out a Simple search first.

  1. Simple search - works in a unified manner across all data providers: it allows you to specify your area of interest, time period, maximal cloud coverage and a set of parameters specific for a data provider.
  2. Native search - is different for each data provider as it closely follows their search APIs. Depending on provider, it may return data that is not actually available for ordering or cannot be imported. To get only the orderable and importable results include the provider-specific filters as explained in the examples below. Note that the simple search always uses these filters in addition to the search parameters you provide.

See examples of both approaches.

Order data import

Once you know which data you need, you can order an import into Sentinel Hub. Again we offer two options for ordering:

  1. Order products - allows you to order specific items/products/scenes by specifying their ids. The ids will normally be extracted from the search results.
  2. Order using query - allows you to create an order by specifying your area of interest time period, cloud coverage (= query). This option allows you to create an order without search for the data first.

If you are not sure which one to use, we suggest you start with Order products. See examples of both approaches.

Check the response of your order data import request to find an area, which will be deduced from your balance if you confirm the order.

The easiest way of ordering your first third party data product(s) is to leave the collectionId field in the order request empty, as the service automatically creates a BYOC collection for you according to the name specified in your order request.

For all subsequent orders of the same kind of data from the same provider, we suggest you reuse the collectionId from the automatically created one to avoid an accumulation of collections in your dashboard. In this way, newly ordered data will be imported into an existing collection, which brings about some benefits. It facilitates the simultaneous use of data from different orders, e.g. from a different point in time or area, and thus makes it easily accessible and comparable via one process request or in one theme layer in EO Browser (please check step 6 in the step by step tutorial for instructions on how to display third party data in EO Browser).

Import data into existing BYOC collection

If you would like to import data into existing BYOC collection, you must provide a collectionId when ordering:

{
"name": "...",
"collectionId": "0X4a57dc-f0e8-4e82-bf96-f74c490422Yf",
"input": {
...
}
}

When ordering data import into an existing BYOC collection you must ensure that band names of new data matches the band names of existing data in this collection. If not, the order will be created but the importing of data will fail (if and after the order is confirmed).

The existing collection should use the S3 bucket sh.tpdi.byoc.eu-central-1. Otherwise, the request for creating an order will return an error.

Confirm order

To start the import of the data you will need to confirm your order. This is to protect you from accidentally creating (huge) orders. See the example of confirming an order.

After you confirm an import, we forward your order to the data provider and wait for them to prepare the data. Once the data is ready, we import the data into a SH BYOC collection. Data is imported asynchronously, which means that it will not be returned in response, and you will need to wait a bit until the process finishes. You can always check the state of the order, see example. The state diagram below shows all possible statuses of an order and order part (= delivery), and actions which trigger transitions among them.

Data access

After the successful import of third party data, you can access it through our Process and OGC API, as well as display it in EO Browser.

See the example for requesting a truecolor image using a Process API request.

For instructions on how to display third party data in EO Browser, please check step 6 in the step by step tutorial.

Order states

CREATEDRUNNINGDONEPARTIALFAILEDa user creates ordera user confirms orderall delivered importedsome deliveries failedall deliveries failed

Delivery states

WAITINGDELIVEREDDELIVERY_FAILEDINGESTINGDONEIMPORT_FAILEDprovider prepares dataprovider fails to deliver dataimport startsimport completesimport fails