Third Party Data Import API

The Third Party Data Import API (or shortly "TPDI") enables you to import data offered by different data provFiders 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 and Planetary Variables data.

Currently, we offer import for:

Planet's PlanetScope data
Planet's SkySat data
Maxar's WorldView data

There is an option in Geocento's EarthImagery service to directly import purchased high-resolution data to your Sentinel Hub account. Please see a detailed description of the service's ordering and Sentinel Hub import process here.

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.

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

Note: When searching for SkySat data you will have to provide your Planet's api key.

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:

Order products - allows you to order specific items/products/scenes by specifying their ids. The ids will normally be extracted from the search results.
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.

Order area

The response of your order request will contain, among other fields, area in km². This is the amount that will be deducted from your quota when you confirm the order. It equals either the ordered area or the minimum order area, whichever is greater; in other words, if you order areas smaller than the provider and constellation-specific minimum amount, you will be billed for the minimum area.

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, SkySat, 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

Delivery states

Failed deliveries are handled as follows:

DELIVERY_FAILED: the quota equivalent of this delivery is automatically reimbursed. This state is often due to temporary outage at the data provider, thus we recommend to submit a new order after a while containing just this delivery.
IMPORT_FAILED: the error is inspected by our team within a few working days and fixed (delivery status changes to " DONE" or "NON_INGESTIBLE")
NON_INGESTIBLE: providers rarely deliver data that is not ingestible by our services. In this case there is not further action that can be taken, but you will still be able to download the original data for your own use.

Note: Deliveries with IMPORT_FAILED or NON_INGESTIBLE statuses are not reimbursed.

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

Subscribing to PlanetScope and Planetary Variable data

For PlanetScope and Planetary Variable 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, data for this AOI.

Creating a subscription

A subscription is created similarly to an "Order using query", except that it must have a starting time, that is, it must include the timeRange filter with the from field set.

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

TimeRange considerations with subscriptions

Subscriptions with a 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.

Note that in subscriptions created before 2023-08-23, the timeRange field referred to the publish time, not the acquisition time. Publish time is typically a few hours, but can also be multiple days or, in case of reprocessed products, even multiple years after the acquisition time. Once ingested into your BYOC collection, however, the sensingTime of the ingested tiles will be correct, i.e. equal to the acquisition time, regardless of when your subscription was created.

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:

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