Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/orders/delivery/) # Delivery ## Delivery Layout and Manifest When using the Orders API, you first create an *order query JSON block* that describes the parameters of order: the kind of imagery you want, a product bundle, any tool operations you want to perform on that imagery, and any delivery instructions, such as requesting STAC as the file format for scenes or delivering the order to a cloud bucket. When the order is fulfilled, a *JSON manifest* is delivered that describes the available assets delivered, as well as the path to those deliverables. For each asset, a *JSON metadata* file is also delivered. It describes the asset and the details about the imagery such as the date it was captured, with what sensors, and under what conditions. The following sections explain the file layout, manifest, metadata, and delivery settings. ### Delivery Layout The order is delivered following a logical structure of orders, imagery-name, and file types, as well as the order manifest.json and a metadata.json file for each image. #### Delivery of scenes The default order delivery layout for scenes is organized as follows: ``` {order-id}/manifest.json {order-id}/{item-type}/{item-id}_metadata.json {order-id}/{item-type}/{asset-filename}.{asset-file-extension} ``` There are slight structural variations when an order is zipped or composited. When zipped, its layout takes the structure below. After it is unzipped, the resulting layout of the contents look like the layout above. ``` {order-id}/manifest.json {order-id}/{archive-filename}.zip ``` When an order is composited, its layout will be organized as follows: ``` {order-id}/manifest.json {order-id}/composite_udm.tif {order-id}/composite.tif {order-id}/{item_id-1}_metadata.json {order-id}/{item_id-1}_{asset-name}_metadata.xml {order-id}/{item_id-2}_metadata.json {order-id}/{item_id-2}_{asset-name}_metadata.xml ``` #### Delivery of mosaics Each mosaics order contains delivery results with the image in COG format, sourcetrace, and UDM2 metadata. The default order delivery layout for mosaics is organized as follows: ``` {order-id}/{mosaic-name}/{quad-id}.tif {order-id}/{mosaic-name}/{quad-id}_metadata.json {order-id}/{mosaic-name}/{quad-id}_sourcetrace.shz {order-id}/{mosaic-name}/{quad-id}_sourcetrace.tif {order-id}/{mosaic-name}/{quad-id}_udm2.tif ``` Zipped vector resources decompress with the metadata.json file for each imagery at the root, and the Shapefile dataset, as in: ``` /{mosaic-name}/{quad-id-vector-1}/_metadata.json /{mosaic-name}/{quad-id-vector-2}/_metadata.json /{mosaic-name}/{quad-id-vector-1}L15-{quad-id-1}.dbf /{mosaic-name}/{quad-id-vector-1}/L15-{quad-id-1}.prj /{mosaic-name}/{quad-id-vector-1}/L15-{quad-id-1}.shp /{mosaic-name}/{quad-id-vector-1}/L15-{quad-id-1}.shx {mosaic-name}/{quad-id-vector-2}L15-{quad_id_}.dbf {mosaic-name}/{quad-id-vector-2}/L15-{quad_id_}.prj {mosaic-name}/{quad-id-vector-2}/L15-{quad_id_}.shp {mosaic-name}/{quad-id-vector-2}/L15-{quad_id_}.shx ``` ### Delivery Manifest The contents of your order are described by a JSON manifest, which is delivered alongside your order. This manifest describes the locations of the order's delivered files with additional metadata, such as the size and a cryptographic hash of file contents. Manifests should be used to learn specifically to which paths data will be delivered. While the file paths referenced in the manifest may be subject to change over time, the order's manifest will always be found at the root directory of where the order data is being delivered. Its location is generated by taking the provided `path_prefix` (if any) and appending the `order_id`, then `manifest.json`. As an example, an order with ID `2284b95e-9e4a-4ab1-a88f-f49dd5f0d883` with a path prefix of `ordered_data/` would result in a manifest at the following key: ``` ordered_data/2284b95e-9e4a-4ab1-a88f-f49dd5f0d883/manifest.json ``` Sample manifest.json file ``` { "name": "", "files": [ { "path": "PSScene/20151119_025740_0c74_metadata.json", "media_type": "application/json", "size": 747, "digests": { "md5": "03571ab27a19569f095e467a79b2a8d4", "sha256": "bc46e2196cd8d8114e62893ffaebae5bb50651ef91140641118fc468814b329c" }, "annotations": { "planet/item_id": "20151119_025740_0c74", "planet/item_type": "PSScene" } }, { "path": "PSScene/20151119_025740_0c74_3B_AnalyticMS.tif", "media_type": "image/tiff", "size": 94649460, "digests": { "md5": "35d48007de9d0671452ac789fbd6b9e4", "sha256": "58a00ec153c203c48cd2bab8ff8059555482aa9c9c66cfa1c90d7637aa893cb6" }, "annotations": { "planet/asset_type": "ortho_analytic_4b", "planet/bundle_type": "analytic_udm2", "planet/item_id": "20151119_025740_0c74", "planet/item_type": "PSScene" } }, { "path": "PSScene/20151119_025740_0c74_3B_AnalyticMS_metadata.xml", "media_type": "text/xml", "size": 10384, "digests": { "md5": "73bf083f08aec24f80fea51dfaceaea9", "sha256": "a89787f7b70a9ec3535637bbe5b5b9e229bcda98cb80dae95c84dc54e0444a89" }, "annotations": { "planet/asset_type": "ortho_analytic_4b_xml", "planet/bundle_type": "analytic_udm2", "planet/item_id": "20151119_025740_0c74", "planet/item_type": "PSScene" } }, { "path": "PSScene/20151119_025740_0c74_3B_udm2.tif", "media_type": "image/tiff", "size": 1652624, "digests": { "md5": "eb4effb691c370297b748f573169fb3f", "sha256": "0b762e81dde1d5be92bf9a39decd98073f5a53c4a6b82eb85176a9bd459f51c7" }, "annotations": { "planet/asset_type": "ortho_udm2", "planet/bundle_type": "analytic_udm2", "planet/item_id": "20151119_025740_0c74", "planet/item_type": "PSScene" } } ] } ``` To find your ordered assets, you may assume all of these paths are relative to the `manifest.json` file. The final location of your assets in this example order include: ``` ordered_data/2284b95e-9e4a-4ab1-a88f-f49dd5f0d883/PSScene/20151119_025740_0c74_3B_AnalyticMS.tif ordered_data/2284b95e-9e4a-4ab1-a88f-f49dd5f0d883/PSScene/20151119_025740_0c74_3B_AnalyticMS_metadata.xml ordered_data/2284b95e-9e4a-4ab1-a88f-f49dd5f0d883/PSScene/20151119_025740_0c74_3B_udm2.tif ordered_data/2284b95e-9e4a-4ab1-a88f-f49dd5f0d883/PSScene/20151119_025740_0c74_metadata.json ``` #### Why you should depend on the manifest file The manifest.json file is the last file delivered for an order, once the order is fully complete. Due to potential delay between the time when an order's files are delivered and when they are accessible for download, we recommend waiting for the manifest before you begin accessing files. ### Metadata File In addition to your requested assets, your order will include a `metadata.json` file. This is a copy of the item-level metadata associated with the asset from our catalog. The `metadata.json` file will appear in the manifest like other assets but will not have `planet/bundle_type` nor `planet/asset_type` annotations. Sample metadata.json file ``` { "id":"20220304_093300_37_2430", "type":"Feature", "geometry":{ "coordinates":[ [ [ 6.167210381911106, 45.95660761074959 ], [ 6.106906222592715, 45.76425741356103 ], [ 6.565372737977715, 45.69159280834395 ], [ 6.628858947551485, 45.88187947653463 ], [ 6.167210381911106, 45.95660761074959 ] ] ], "type":"Polygon" }, "properties":{ "acquired":"2022-03-04T09:33:00.375453Z", "anomalous_pixels":0, "clear_confidence_percent":87, "clear_percent":63, "cloud_cover":0, "cloud_percent":0, "ground_control":true, "gsd":4.1, "heavy_haze_percent":0, "instrument":"PSB.SD", "item_type":"PSScene", "light_haze_percent":0, "pixel_resolution":3, "provider":"planetscope", "published":"2022-03-04T22:56:32Z", "publishing_stage":"finalized", "quality_category":"test", "satellite_azimuth":102.2, "satellite_id":"2430", "shadow_percent":2, "snow_ice_percent":34, "strip_id":"5455214", "sun_azimuth":141.5, "sun_elevation":30.3, "updated":"2022-03-12T02:38:49Z", "view_angle":5.1, "visible_confidence_percent":75, "visible_percent":100 } } ``` ## STAC Metadata For scenes orders, you can also opt in to receiving additional metadata in the [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/en) format. STAC provides a standardized format for a wide range of geospatial information, including satellite imagery and accompanying assets. note This is a beta feature available only for scenes orders at this time. The precise version of STAC and STAC extensions used may change as the specifications are finalized and our implementation is further developed. STAC is only available with `standard` delivery layout format, and is not supported for the `legacy_deprecated` layout format. warning The initial STAC metadata from Planet contained a `published` field for the original publication date time. This is still available but "deprecated", and the `created` property is now used for the same information, aligning with the STAC standard. ### STAC Files and Structure Each order contains: * A single [STAC Catalog](https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md) file at the root of the order that represents the entire order's contents. It contains references to each item type Collection in the order. * filename: **`catalog.json`** * A [STAC Collection](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md) file for each item type in the order with references to each item associated with the item type. * filename: **`{item_type}_collection.json`** * A [STAC Item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) file for each Planet item in the order with an asset link to each file associated with the item. * filename: **`{item_id}.json`** STAC files are provided as a [self-contained catalog](https://github.com/radiantearth/stac-spec/blob/master/best-practices.md#self-contained-catalogs) with relative links within the context of a specific order. To receive order links in the STAC format, add a `metadata` section with a `stac` field to the Create Order request. * JSON * Python SDK ``` "metadata": { "stac": {} } ``` ``` from planet.order_request import build_request, product order_request = build_request( name="example_metadata_order", products=[ product(["20170614_113217_3163208_RapidEye-5"], "analytic", "REOrthoTile") ], stac=True, ) ``` Example STAC Item output file ``` { "type": "Feature", "stac_version": "1.0.0", "id": "20201127_075950_38_2262", "properties": { "datetime": "2020-11-27T07:59:50.380214Z", "eo:cloud_cover": 3, "pl:ground_control": true, "gsd": 4, "pl:item_type": "PSScene", "pl:pixel_resolution": 3, "constellation": "planetscope", "pl:ps4b_geometry": { "coordinates": [ [ [ 22.693170159841205, -19.427700915034176 ], [ 22.652554394892615, -19.613619428667235 ], [ 22.981065705747977, -19.677156600392 ], [ 23.020946340859247, -19.491989374857926 ], [ 22.693170159841205, -19.427700915034176 ] ] ], "type": "Polygon" }, "published": "2020-11-28T02:05:14Z", "pl:publishing_stage": "finalized", "pl:quality_category": "standard", "view:azimuth": 95.4, "platform": "2262", "pl:strip_id": "3937348", "view:sun_azimuth": 98.9, "view:sun_elevation": 58.3, "updated": "2021-03-18T08:53:46Z", "view:off_nadir": 3, "instruments": [ "PSB.SD" ], "proj:epsg": 32734, "proj:shape": [ 9554, 13269 ], "proj:transform": [ 3.0, 0.0, 672798.0, 0.0, -3.0, 7851336.0, 0.0, 0.0, 1.0 ], "proj:bbox": [ 672798.0, 7822674.0, 712605.0, 7851336.0 ] }, "geometry": { "coordinates": [ [ [ 22.693170159841205, -19.427700915034176 ], [ 22.652554394892615, -19.613619428667235 ], [ 22.981065705747977, -19.677156600392 ], [ 23.020946340859247, -19.491989374857926 ], [ 22.693170159841205, -19.427700915034176 ] ] ], "type": "Polygon" }, "links": [ { "rel": "root", "href": "../catalog.json", "type": "application/json" }, { "rel": "collection", "href": "./PSScene_collection.json", "type": "application/json" }, { "rel": "parent", "href": "./PSScene_collection.json", "type": "application/json" } ], "assets": { "20201127_075950_38_2262_metadata_json": { "href": "./20201127_075950_38_2262_metadata.json", "type": "application/json" }, "20201127_075950_38_2262_3B_AnalyticMS_8b_tif": { "href": "./20201127_075950_38_2262_3B_AnalyticMS_8b.tif", "type": "image/tiff", "pl:asset_type": "ortho_analytic_8b", "pl:bundle_type": "analytic_8b_udm2" }, "20201127_075950_38_2262_3B_AnalyticMS_8b_metadata_xml": { "href": "./20201127_075950_38_2262_3B_AnalyticMS_8b_metadata.xml", "type": "text/xml", "pl:asset_type": "ortho_analytic_8b_xml", "pl:bundle_type": "analytic_8b_udm2" }, "20201127_075950_38_2262_3B_udm2_tif": { "href": "./20201127_075950_38_2262_3B_udm2.tif", "type": "image/tiff", "pl:asset_type": "ortho_udm2", "pl:bundle_type": "analytic_8b_udm2" } }, "bbox": [ 22.652554394892615, -19.677156600392, 23.020946340859247, -19.427700915034176 ], "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" ], "collection": "9d2c91f8-77b3-4e80-a55b-7c8256937508: PSScene" } ``` ## Zipping Results With the zip delivery option, you can receive the output of your order as a "per order" or "per bundle" zip archive. Zipping is not supported for mosaic orders. #### Parameters | Property | Required | Description | | --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **archive\_type** | Optional | Only `zip` format is supported. | | **archive\_filename** | Optional | The name of the archive file you will receive. You can use template variables `{{name}}` and `{{order_id}}` and in the string, which vary based on whether the order is per-bundle or per-order (for example `single_archive`) and are described in more detail below. | | **single\_archive** | Optional | When `true`, this option will archive all bundles together in a single file. | note When using zip delivery with **SkySatCollect**, **TanagerScene**, or **PelicanScene** item types, orders are limited to **50 items** per order. This applies when either `archive_filename` or `single_archive` is set. Orders exceeding this limit will be rejected with an error. Other item types remain subject to the standard 500-item limit. #### Per bundle zipping For per bundle zipping (For example, when `single_archive` is null or `false`), the archive filename variable `{{name}}` will return `{item_type}_{item_id}_{product_bundle}` and `{{order_id}}` will return the `order_id`. * JSON * Python SDK ``` "delivery": { "archive_type": "zip", "archive_filename": "{{name}}_{{order_id}}.zip" } ``` ``` from planet.order_request import delivery delivery_config = delivery( archive_type="zip", archive_filename="{{name}}_{{order_id}}.zip" ) ``` Output files (`order_id` = `68b2e5c0-aaf0-49cb-b5a8-13a96083dd41`): ``` 68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/PSScene_20151119_025741_0c74_analytic_68b2e5c0-aaf0-49cb-b5a8-13a96083dd41.zip 68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/PSScene_20151119_025740_0c74_analytic_68b2e5c0-aaf0-49cb-b5a8-13a96083dd41.zip 68b2e5c0-aaf0-49cb-b5a8-13a96083dd41/manifest.json ``` #### Whole order zipping For whole order zipping (For example, when `single_archive` is true), the archive filename variable `{{name}}` will list the order `name` and `{{order_id}}` will list the `order_id`. * JSON * Python SDK ``` "delivery": { "archive_type": "zip", "single_archive": true, "archive_filename": "{{name}}_{{order_id}}.zip" } ``` ``` from planet.order_request import delivery delivery_config = delivery( archive_type="zip", single_archive=True, archive_filename="{{name}}_{{order_id}}.zip", ) ``` Output files (`order_id` = `1b36c36c-8965-4e6f-9eef-ee9694f3d69c`, `name` = `per-order-zipped-order`): ``` 1b36c36c-8965-4e6f-9eef-ee9694f3d69c/per-order-zipped-order_1b36c36c-8965-4e6f-9eef-ee9694f3d69c.zip 1b36c36c-8965-4e6f-9eef-ee9694f3d69c/manifest.json ``` ## Delivery to Cloud Storage You may choose to have your order delivered to a number of cloud storage providers. For any cloud storage provider, you will need to create an account with both *write* and *delete* access. When creating an order with bucket delivery, Planet checks the bucket permissions linked to your token by first attempting to deliver a file named `planetverify.txt` and then immediately deleting it. If Planet has the adequate permissions, you will not see this file. If you do see this file in your buckets, we recommend that you review your permissions and make sure that Planet has both write and delete access. warning When creating an order, a user must input their credentials for successful cloud delivery of Planet data. This poses a potential security risk. For secure handling of cloud service credentials in the request, please ensure that access is limited to the desired delivery path with no read/write access for any other storage locations or cloud services. ### Amazon S3 For Amazon S3 delivery you will need an AWS account with `GetObject`, `PutObject`, and `DeleteObject` permissions. #### Parameters | Property | Required | Description | | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **aws\_access\_key\_id** | Required | AWS credentials. | | **aws\_secret\_access\_key** | Required | AWS credentials. | | **bucket** | Required | The name of the bucket that will receive the order output. | | **aws\_region** | Required | The region where the bucket lives in AWS. | | **path\_prefix** | Optional | An optional string that will prepend to the files delivered to the bucket. A forward slash (/) is treated as a folder. All other characters are added as a prefix to the files. | * JSON * Python SDK ``` "delivery": { "amazon_s3": { "bucket": "foo-bucket", "aws_region": "us-east-2", "aws_access_key_id": "$AWS_ACCESS_KEY_ID", "aws_secret_access_key": "$AWS_SECRET_KEY", "path_prefix": "folder1/prefix" } } ``` ``` from os import getenv from planet.order_request import amazon_s3 AWS_ACCESS_KEY_ID = getenv("AWS_ACCESS_KEY_ID") AWS_SECRET_KEY = getenv("AWS_SECRET_KEY") delivery = amazon_s3( aws_access_key_id=AWS_ACCESS_KEY_ID, aws_secret_access_key=AWS_SECRET_KEY, bucket="foo-bucket", aws_region="us-west-2", path_prefix="folder1/prefix", ) ``` ### Google Cloud Storage For Google Cloud Storage delivery, a [service account](https://cloud.google.com/docs/authentication/client-libraries) with `storage.objects.create`, `storage.objects.get`, and `storage.objects.delete` permissions is required. Access should be restricted to the specified delivery path, without read or write permissions to other storage locations. #### Preparing your Google Cloud Storage credentials The Google Cloud Storage delivery option requires a single-line base64 version of your service account credentials for use by the credentials parameter. Download your service account credentials in JSON format (not P12) and encode them as a base64 string with a command line operation such as: ``` cat my_creds.json | base64 ``` #### Parameters | Property | Required | Description | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **credentials** | Required | GCS credentials. | | **bucket** | Required | The name of the GCS bucket which will receive the order output. | | **path\_prefix** | Optional | An optional string that will prepend to the files delivered to the bucket. A forward slash (/) is treated as a folder. All other characters are added as a prefix to the files. | * JSON * Python SDK ``` "delivery": { "google_cloud_storage": { "bucket": "foo-bucket", "credentials": "$GCS_CREDENTIALS", "path_prefix": "folder1/prefix" } } ``` ``` from os import getenv from planet.order_request import google_cloud_storage GCS_CREDENTIALS = getenv("GCS_CREDENTIALS") delivery = google_cloud_storage( bucket="foo-bucket", credentials=GCS_CREDENTIALS, path_prefix="folder1/prefix", ) ``` ### Google Earth Engine The Planet GEE Delivery Integration simplifies the process of incorporating Planet data into GEE projects by creating a direct connection between the Planet Orders API and GEE. To use the integration, users must sign up for an Earth Engine account, create a Cloud Project, enable the Earth Engine API, and grant a [Google service account](https://cloud.google.com/iam/docs/service-account-overview) access to deliver data to their GEE project. Follow the steps found in our [GEE Guide](https://docs.planet.com/platform/integrations/google-earth-engine/order-imagery-gee.md#orders-api-delivery) to get started. #### Parameters | Property | Required | Description | | --------------- | -------- | ------------------------------ | | **project** | Required | The GEE project name. | | **collection** | Required | The GEE image collection name. | | **credentials** | Optional | Service account credentials. | * JSON * Python SDK ``` "delivery": { "google_cloud_storage": { "project": "project-name", "collection": "gee-collection" "credentials": "$GEE_CREDENTIALS", } } ``` ``` from planet.order_request import google_earth_engine delivery = google_earth_engine( project="foo-project", collection="foo-collection", ) ``` ### Microsoft Azure For Microsoft Azure delivery you will need an Azure account with `read`, `write`, `delete`, and `list` permissions. #### Parameters | Property | Required | Description | | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **account** | Required | Azure account name. | | **container** | Required | The name of the container which will receive the order output. | | **sas\_token** | Required | [Azure Shared Access Signature token](https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview). Token should be specified without a leading `?`. (for example `sv=2017-04-17u0026si=writersr=cu0026sig=LGqc` rather than `?sv=2017-04-17u0026si=writersr=cu0026sig=LGqc`) | | **storage\_endpoint\_suffix** | Optional | To deliver your order to a sovereign cloud a `storage_endpoint_suffix` should be set appropriately for your cloud. The default is `core.windows.net`. | | **path\_prefix** | Optional | An optional string that will prepend to the files delivered to the bucket. A forward slash (`/`) is treated as a folder. All other characters are added as a prefix to the files. | * JSON * Python SDK ``` "delivery": { "azure_blob_storage": { "account": "account-name", "container": "container-name", "sas_token": "$AZURE_SAS_TOKEN", "storage_endpoint_suffix": "core.windows.net", "path_prefix": "folder1/prefix" } } ``` ``` from os import getenv from planet.order_request import azure_blob_storage AZURE_SAS_TOKEN = getenv("AZURE_SAS_TOKEN") delivery = azure_blob_storage( account="account-name", container="container-name", sas_token=AZURE_SAS_TOKEN, storage_endpoint_suffix="core.windows.net", path_prefix="folder1/prefix", ) ``` ### Oracle Cloud Storage For Oracle Cloud Storage delivery you need an Oracle account with `read`, `write`, and `delete` permissions. For authentication you need a Customer Secret Key which consists of an Access Key/Secret Key pair. #### Parameters | Property | Required | Description | | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **customer\_access\_key\_id** | Required | Customer Secret Key credentials. | | **customer\_secret\_key** | Required | Customer Secret Key credentials. | | **bucket** | Required | The name of the bucket that will receive the order output. | | **region** | Required | The region where the bucket lives in Oracle. | | **namespace** | Required | Object Storage namespace name. | | **path\_prefix** | Optional | An optional string that will prepend to the files delivered to the bucket. A forward slash (/) is treated as a folder. All other characters are added as a prefix to the files. | * JSON * Python SDK ``` "delivery": { "oracle_cloud_storage": { "bucket": "foo-bucket", "namespace": "foo-namespace", "region": "us-sanjose-1", "customer_access_key_id": "$ORACLE_ACCESS_ID", "customer_secret_key": "$ORACLE_SECRET_KEY", "path_prefix": "folder1/prefix" } } ``` ``` from os import getenv from planet.order_request import oracle_cloud_storage ORACLE_ACCESS_ID = getenv("ORACLE_ACCESS_ID") ORACLE_SECRET_KEY = getenv("ORACLE_SECRET_KEY") delivery = oracle_cloud_storage( customer_access_key_id=ORACLE_ACCESS_ID, customer_secret_key=ORACLE_SECRET_KEY, bucket="foo-bucket", region="us-sanjose-1", namespace="foo-namespace", path_prefix="folder1/prefix", ) ``` ### S3 Compatible Delivery S3 compatible delivery allows data to be sent to any cloud storage provider that supports the Amazon S3 API. To use this delivery method, you'll need an account with `read`, `write`, and `delete` permissions on the target bucket. Authentication is performed using an Access Key and Secret Key pair. note While this delivery method is designed to work with any S3-compatible provider, not all integrations have been explicitly tested. Some providers may advertise S3 compatibility but deviate from the API in subtle ways that can cause issues. We encourage testing with your chosen provider to ensure compatibility. Pay particular attention to the `use_path_style` parameter, as it's a common source of issues. For example, Oracle Cloud requires `use_path_style` to be `true`, while Open Telekom Cloud requires it to be `false`. #### Parameters | Property | Required | Description | | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **access\_key\_id** | Required | Access key for authentication. | | **secret\_access\_key** | Required | Secret key for authentication. | | **bucket** | Required | S3-compatible bucket to send results to. | | **region** | Required | Region for the S3-compatible service. | | **endpoint** | Required | S3-compatible service endpoint. | | **use\_path\_style** | Optional | Whether to use path-style addressing (default is `false`). If `true`, the bucket name is included in the URL path; if `false`, it's included in the hostname. | | **path\_prefix** | Optional | A string to prepend to delivered files. A forward slash (`/`) is treated as a folder; all other characters are added directly as a prefix to file names. | * JSON * Python SDK ``` "delivery": { "s3_compatible": { "endpoint": "https://s3.foo.com", "bucket": "foo-bucket", "region": "foo-region", "access_key_id": "$ACCESS_KEY_ID", "secret_access_key": "$SECRET_ACCESS_KEY", "use_path_style": false, "path_prefix": "folder1/prefix" } } ``` ``` from os import getenv from planet.order_request import s3_compatible ACCESS_KEY_ID = getenv("ACCESS_KEY_ID") SECRET_ACCESS_KEY = getenv("SECRET_ACCESS_KEY") delivery = s3_compatible( endpoint="https://s3.foo.com", bucket="foo-bucket", region="foo-region", access_key_id=ACCESS_KEY_ID, secret_access_key=SECRET_ACCESS_KEY, use_path_style=False, path_prefix="folder1/prefix", ) ``` ## Destinations Destination delivery allows data to be sent to any destination created in the [Destinations API](https://docs.planet.com/develop/apis/destinations.md). By using destination references, you avoid including credentials in every request, improving both security and convenience. To create an order using a destination, use the following delivery format: * JSON ``` "delivery": { "destination": { "ref": "pl:destinations/my-s3-destination-CKxV9io", "path_prefix": "planet-scenes" // optional path prefix } } ``` To create an order using the organization's default destination, specify the default alias: * JSON ``` "delivery": { "destination": { "ref": "pl:destinations/default", "path_prefix": "planet-scenes" // optional path prefix } } ``` note Destination credentials are not revalidated when referenced in other APIs. If credentials expire or change, update them via the Destinations API to avoid delivery failures. tip To filter orders by their associated destination, use the `destination_ref` query parameter with the List Orders endpoint: * CLI ``` curl -X GET "https://api.planet.com/compute/ops/orders/v2?destination_ref=pl:destinations/my-s3-destination-CKxV9io" \ --include \ -H "Authorization: api-key $PL_API_KEY" ``` ## Hosting You can deliver data to a data collection hosted on the Planet Insights Platform to visualize and stream your data in platform tools. The hosting block eliminates the need to use the delivery block. Specifying both is not allowed. You can browse your collections on the Planet Insights Platform under [Data collections](https://insights.planet.com/data/collections). ### Parameters | Property | Required | Description | | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **collection\_id** | Optional | ID of the target collection to delivery data to. If omitted, a collection will be created on your behalf, and its ID will be returned in the response with the collection name the same as the order name. If included, the collection must be compatible with the order, which will be validated during order creation. | | **configuration\_id** | Optional | Specifies the ID of the layer configuration. If `create_configuration` is enabled, this field will contain the ID of the newly created layer configuration. Any provided value will be ignored. | | **create\_configuration** | Optional | Determines whether to automatically create a layer configuration for your collection. The configuration will be assigned the same name as the collection. If no compatible configuration is found, the operation will return an error. The `collection_id` parameter cannot be specified when `create_configuration` is set to true. | To reuse a collection across multiple orders with the same data type, first omit the `collection_id` parameter in your initial request to auto-create a collection. Then, use the returned `collection_id` for all subsequent requests. This links all orders to the same collection efficiently. Importantly, orders with different data types cannot share a collection. As an example, orders with PSScene 8 band assets and SkySatScene assets cannot share the same collection. #### No collection ID provided * JSON * Python SDK ``` "hosting": { "sentinel_hub": {} } ``` ``` from planet import order_request delivery = order_request.sentinel_hub() ``` #### Collection ID provided * JSON * Python SDK ``` "hosting": { "sentinel_hub": { "collection_id": "my_collection_id" } } ``` ``` from planet import order_request delivery = order_request.sentinel_hub(collection_id="my-collection-id") ``` Please note the following: * Only the following tools are permitted: * [`harmonize`](https://docs.planet.com/develop/apis/orders/tools.md#harmonize) * [`toar`](https://docs.planet.com/develop/apis/orders/tools.md#top-of-atmosphere-reflectance-toar) * [`file_format` (COG)](https://docs.planet.com/develop/apis/orders/tools.md#file-format) * [`clip`](https://docs.planet.com/develop/apis/orders/tools.md#clip) * The [`file_format` (COG)](https://docs.planet.com/develop/apis/orders/tools.md#file-format) tool will automatically be added, `NITF` not supported, and cannot be removed * Only one element in the `products` list will be accepted * Fallback bundles are not supported * Mosaics ordering is not supported * Non-orthorectified assets (`basic_*` bundles) are not supported note When delivering to a data collection, collection tiles may show the warning `coverGeometry is partially outside tileGeometry`. This occurs when the geometry in the delivered metadata does not match the tile's pixel footprint, which can happen due to data processing intricacies. The data will still be ingested, but may result in `nodata` pixels within the tile when requesting the imagery.