Skip to main content

Third-Party Data Import API

Deprecation notice

Using this API for Planet data is deprecated but remains functional until November 11, 2026. Migrate to the Orders and Subscriptions 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 for available data
  • Order the import of selected data into Planet Insights Platform

TPDI is closely related to the BYOC service, since purchased third-party data is imported into BYOC collections and accessible through the Processing or OGC API.

To get started, check out the API reference and examples.

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

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.

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.

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.

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.

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

See the example for requesting a truecolor image using the Processing API.

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.

Last updated on