Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/tpdi/)

# Third-Party Data Import API

Deprecation notice

Using this API for Planet data is [deprecated](https://community.planet.com/product-updates/sunset-of-third-party-data-import-tpdi-api-for-planet-data-6453) but remains functional until November 11, 2026. Migrate to the [Orders](https://docs.planet.com/develop/apis/orders.md) and [Subscriptions](https://docs.planet.com/develop/apis/subscriptions.md) APIs as soon as possible. The API remains fully supported for importing Maxar's **WorldView** data.

The Third-Party Data Import API (TPDI) lets you import data offered by different data providers into Planet Insights Platform. The API allows you to:

* [Search](#searching-data) for available data
* [Order](#order-data-import) the import of selected data into Planet Insights Platform

TPDI is closely related to the [BYOC service](https://docs.planet.com/develop/apis/byoc.md), since purchased third-party data is imported into BYOC collections and accessible through the [Processing](https://docs.planet.com/develop/apis/processing.md) or [OGC API](https://docs.planet.com/platform/integrations/ogc.md).

To get started, check out the [API reference](https://docs.planet.com/develop/apis/tpdi/reference.md) and [examples](https://docs.planet.com/develop/apis/tpdi/examples-worldview.md).

note

Certain error codes and messages are forwarded from data provider APIs. See their documentation for more details.

## CRS Support

Find the list of supported CRSs in the [Processing API documentation](https://docs.planet.com/develop/apis/processing.md#crs-support). The API transforms coordinates to `http://www.opengis.net/def/crs/OGC/1.3/CRS84` before requesting data from a provider.

## Workflow

### Searching Data

The Search API lets you browse third-party data archives. It is useful when you are not sure what data is available or which scenes you want to order. There are 2 search interfaces:

1. **Simple search** - Specify your area of interest, time period, maximum cloud coverage, and provider-specific parameters.
2. **Native search** - different for each data provider, closely following their Search APIs. Depending on the provider, it may return data that is not available for ordering. To get only orderable results, include provider-specific filters as shown in the examples. Note that simple search always applies these filters automatically.

See [examples of both approaches](https://docs.planet.com/develop/apis/tpdi/examples-worldview.md#search).

### Order Data Import

Once you know which data you need, you can order an import into Planet Insights Platform. Two ordering options are available:

1. **Order products** - order specific items by specifying their IDs, extracted from search results.
2. **Order using query** - create an order by specifying your area of interest, time period, and cloud coverage. This lets you place an order without searching first.

See [examples of both approaches](https://docs.planet.com/develop/apis/tpdi/examples-worldview.md#order).

#### Order Area

The order response contains an `area` field in km². This is the amount deducted from your quota when you confirm the order. It equals either the ordered area or the minimum order area, whichever is greater. If you order an area smaller than the minimum (5 km² for WorldView), you will be billed for the minimum area.

#### Import Data into an Existing BYOC Collection

If you leave the `collectionId` field empty in the order request, the service automatically creates a new BYOC collection with the name specified in your order and imports the data into it.

We recommend always specifying a `collectionId` when ordering. The best approach is to maintain one collection per data type (for example, WorldView) and reuse it for each new order of the same type. This makes data from different orders accessible and comparable through a single process request or in the [Browser](https://insights.planet.com/analyze/browser/).

To import data into an existing BYOC collection, provide a `collectionId` in the order request:

```
{

    "name": "...",

    "collectionId": "0X4a57dc-f0e8-4e82-bf96-f74c490422Yf",

    "input": {

        ...

    }

}
```

When ordering into an existing BYOC collection, ensure that:

* Band names of the new data match the band names of existing data in the collection. If they do not match, the order is created but importing will fail after confirmation. Data from different third-party providers cannot be mixed in the same BYOC collection due to differences in band count, names, and type.
* The existing BYOC collection is in the `sh.tpdi.byoc.eu-central-1` S3 bucket. Otherwise, the order request returns an error.

#### Confirm Order

To start the data import, you must confirm your order. This step protects you from accidentally creating large orders. See the [example for confirming an order](https://docs.planet.com/develop/apis/tpdi/examples-worldview.md#confirm-the-order).

After confirmation, the order is forwarded to the data provider. Once the provider prepares the data, it is imported into a Planet Insights Platform BYOC collection. Data import is asynchronous, so you need to wait for the process to finish. You can check order status at any time. See the [example for getting order information](https://docs.planet.com/develop/apis/tpdi/examples-worldview.md#get-order-information).

#### Order States

#### Delivery States

```mermaid
stateDiagram
    [*] --> WAITING
    WAITING --> DELIVERED: provider prepares data
    WAITING --> DELIVERY_FAILED: provider fails to deliver data
    DELIVERED --> PREPARING: conversion to COG starts
    PREPARING --> INGESTING: ingestion starts
    INGESTING --> DONE: ingestion completes
    INGESTING --> NON_INGESTIBLE: ingestion fails
    INGESTING --> IMPORT_FAILED: ingestion fails
    PREPARING --> IMPORT_FAILED: conversion to COG fails
```

Failed deliveries are handled as follows:

* **DELIVERY\_FAILED**: The quota equivalent of this delivery is automatically reimbursed. This state is often due to a temporary outage at the data provider. Submit a new order after a while containing only 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 cannot be ingested. In this case no further action can be taken, but you can still download the original data for your own use.

note

Deliveries with IMPORT\_FAILED or NON\_INGESTIBLE statuses are **not** reimbursable.

#### Data Access and Download

**Access through Planet Insights Platform**

After a successful import, you can access third-party data through Planet Insights Platform APIs or display it in the [Browser](https://insights.planet.com/analyze/browser/).

See the [example for requesting a truecolor image using the Processing API](https://docs.planet.com/develop/apis/tpdi/examples-worldview.md#access-worldview-data-in-a-byoc-collection-and-process-a-truecolor-image).

**Original Data Download**

You can download the data and associated metadata in the original form, exactly as delivered by the provider. Files are provided in COG (Cloud Optimized GeoTIFF) format and you can download individual files one at a time.

Learn more about [downloading from data collections](https://docs.planet.com/platform/get-started/access-data/data-collections.md#downloading-from-data-collections).

```mermaid
stateDiagram
    [*] --> CREATED: a user creates order
    CREATED --> RUNNING: a user confirms order
    RUNNING --> DONE: all delivered imported
    RUNNING --> PARTIAL: some deliveries failed
    RUNNING --> FAILED: all deliveries failed
```