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,
  • order the import of selected data into Sentinel Hub,
  • subscribe to all data matching your criteria, which are then automatically imported into Sentinel Hub. Subscribing is supported only for Planet's PlanetScope data.

Currently, we offer import for:

We might offer an import of other third party data in the future.

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. To get to know the Third Party Data Import API, check out API reference and examples. Note: Certain error codes and error messages are forwarded from data provider's APIs, therefore more information about these can be found in their documentation.

CRS support

Find the list of supported CRSs here. Sentinel Hub will transform the coordinates to http://www.opengis.net/def/crs/OGC/1.3/CRS84 before requesting the data from a provider.

Workflow

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.

The response of your order request will contain, among other fields, the ordered area in km2. This is the amount that will be deduced from your quota when you confirm the order. Note: For PlanetScope data, the quota in Sentinel Hub does not reflect your actual usage. Make sure your order is in line with the Hectares under Management (HUM) model to avoid overage fees, more details here.

Import data into existing BYOC collection

If you leave the collectionId field in the order request empty, the service will automatically create a new BYOC collection, with the name specified in your order request, and import the ordered data into it.

In general we recommend that you always specify collectionId when ordering. The best approach is to have one collection per data type (e.g. PlanetScope, Pleiades, SPOT, WorldView) and reuse it every time you order data of corresponding type. 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 of interest, 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).

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). Data from different third party providers cannot be mixed in the same BYOC collection due to different band number, names, and type.

  • the existing BYOC collections is in sh.tpdi.byoc.eu-central-1 S3 bucket. 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.

Order states

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

Delivery states

WAITINGDELIVEREDDELIVERY_FAILEDPREPARINGINGESTINGDONEIMPORT_FAILEDprovider prepares dataprovider fails to deliver dataconversion to COG startsingestion startsingestion completesingestion failsconversion to COG fails

Data access and download

Data access through Sentinel Hub

After the successful import of third party data, you can access it through any Sentinel Hub 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.

Original data download

In addition to accessing the data through Sentinel Hub, you can also request a list of delivery files and download all the data and the associated metadata in the original form, exactly as it was delivered by the data provider. This can be done with the API (see API reference for order delivery) or directly in the Sentinel Hub Dashboard user interface.

You can choose between downloading individual files, or downloading all the files at once in a zip archive. In case the ZIP archive is large and the download is interrupted for any reason, the service supports continuation - for example, by using curl and employing the -C Continue switch. Please note that the files, names, and formats are provider-specific.

tpdi download

Subscribing to PlanetScope data

For PlanetScope data, we also offer an option to subscribe to all data that matches your criteria. This allows you to subscribe to you area of interest and SH will automatically import all, past and future, PlanetScope data for this AOI.

Creating a subscription

A subscription is created similarly to an "Order using query", except that it must:

  • request the only asset type currently supported for subscriptions, i.e. analytic_sr_udm2, and consequently set harmonizeTo to NONE,
  • have a starting time, that is, it must include the timeRange filter with the from field set.

Subscriptions with specified end date (i.e. to field in timeRange) will stop once all data within the requested interval has been imported. Subscriptions without specified end date will continue running until you cancel them, provided your API key remains valid.

We recommend specifying collectionId when creating a subscription similarly as with individual orders.

See also an example of how to create a subscription.

Subscription workflow

Subscriptions with the status CREATED must be confirmed to start RUNNING. They can be cancelled at any time. See also examples of confirming and inspecting a subscription. The full workflow is as follows:

CREATEDRUNNINGCOMPLETEDCANCELLEDFAILEDuser creates a subscriptionuser confirms the subscriptionall data up to`timeRange.to` importeduser cancelsthe subscriptionsubscription has stoppeddue to an error

As a subscription runs, deliveries are created for all matched data. The deliveries are processed in the same way as for orders. See also examples of listing subscription's deliveries

Data access and download

Data is accessed and downloaded in the same way as with individual orders. For subscriptions, data download API differs a bit from individual order delivery - see subscriptions delivery API reference.

  • For individual orders, the whole process of searching, ordering and visualizing commercial data can be completed in EO Browser directly. See this video for a demonstration. August 9, 2021
  • To integrate commercial data into your application, use our TPDI API. Check our webinar on Commercial data, where you will learn how to search and order commercial data using the API, visualize it in EO Browser, generate time-series and view statistical information, import data into QGIS and get commercial data sponsored. January 20, 2021
  • See also a step by step PDF tutorial on ordering and visualizing commercial data using EO Browser, Requests Builder and Postman.
  • See this FAQ about subscriptions for a step-by-step guide on how to subscribe to PlanetScope data, along with other useful information about them.
  • Read our blog post on commercial data: Commercial datasets done (mostly) right — always fresh - January 25, 2022