Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/subscriptions/delivery/) # Delivery ## Delivery Schema The schema for Subscriptions API `delivery` below: ``` "delivery": { "type": "cloud-storage-provider", "parameters": { "parameter1-name": "p1-value", "parameter2-name": "p2-value" } } ``` ## Delivery Layout When data is delivered to your cloud storage for your Subscription, the files will be by the following layout scheme: `//...` For example, file `20170716_144316_1041_3B_AnalyticMS.tif` for item `20170716_144316_1041` as output for subscription `0ee41665-ab3b-4faa-98d1-25738cdd579c` will be delivered to the path: `0ee41665-ab3b-4faa-98d1-25738cdd579c/20170716_144316_1041/20170716_144316_1041_3B_AnalyticMS.tif`. ## Delivery to Cloud Storage You may choose to have your subscription delivered to a number of cloud storage providers. For any cloud storage provider, you must create an account with both *write* and *delete* access. Activation and processing for direct download is not currently supported. When creating a subscription with cloud 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 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 a subscription, users 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. You can have your subscription delivered to several cloud storage providers. You must create an account for any cloud storage provider with both *write* and *delete* access. ### 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 subscription 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. Must be 1 – 128 characters long, use only Unicode letters, and -, ., \_, /, does not start or end with -, \_, or /, and does not allow trailing or consecutive -, \_, or /. | * JSON * Python SDK ``` "delivery": { "type": "amazon_s3", "parameters": { "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.subscription_request import amazon_s3 AWS_ACCESS_KEY_ID = getenv("AWS_ACCESS_KEY_ID") AWS_SECRET_KEY = getenv("AWS_SECRET_KEY") aws_delivery = amazon_s3( aws_access_key_id=AWS_ACCESS_KEY_ID, aws_secret_access_key=AWS_SECRET_KEY, aws_region="us-east-2", bucket="bucket-name", 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. To download your service account credentials in JSON format (not P12) and encode them as a base64 string, you can use 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 that 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. Must be 1 – 128 characters long, use only Unicode letters, and -, ., \_, /, does not start or end with -, \_, or /, and does not allow trailing or consecutive -, \_, or /. | * JSON * Python SDK ``` "delivery": { "type": "google_cloud_storage", "parameters": { "bucket": "foo-bucket", "credentials": "$GCS_CREDENTIALS", "path_prefix":"folder1/prefix" } } ``` ``` from planet.subscription_request import google_cloud_storage from os import getenv GCS_CREDENTIALS = getenv("GCS_CREDENTIALS") gcs_delivery = google_cloud_storage( bucket="bucket-name", credentials=GCS_CREDENTIALS, path_prefix="folder1/prefix", ) ``` ### Google Earth Engine The Planet GEE Delivery Integration simplifies incorporating Planet data into GEE projects by directly connecting between the Planet Subscriptions 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#subscriptions-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 ``` "delivery": { "type": "google_earth_engine", "parameters": { "project": "project-name", "collection": "gee-collection" "credentials": "$GEE_CREDENTIALS", } } ``` ### 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 container name which will receive the subscription output. | | **sas\_token** | Required | [Azure Shared Access Signature token](https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview). The 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. Must be 1 – 128 characters long, use only Unicode letters, and -, ., \_, /, does not start or end with -, \_, or /, and does not allow trailing or consecutive -, \_, or /. | * JSON * Python SDK ``` "delivery": { "type": "azure_blob_storage", "parameters": { "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.subscription_request import azure_blob_storage AZURE_SAS_TOKEN = getenv("AZURE_SAS_TOKEN") azure_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 subscription 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. Must be 1 – 128 characters long, use only Unicode letters, and -, ., \_, /, does not start or end with -, \_, or /, and does not allow trailing or consecutive -, \_, or /. | * JSON * Python SDK ``` "delivery": { "type": "oracle_cloud_storage", "parameters": { "bucket": "foo-bucket", "namespace": "ORACLE_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.subscription_request import oracle_cloud_storage ORACLE_ACCESS_ID = getenv("ORACLE_ACCESS_ID") ORACLE_SECRET_KEY = getenv("ORACLE_SECRET_KEY") oracle_delivery = oracle_cloud_storage( customer_access_key_id=ORACLE_ACCESS_ID, customer_secret_key=ORACLE_SECRET_KEY, bucket="bucket-name", region="us-sanjose-1", namespace="ORACLE_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 | 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. Must be 1 – 128 characters long, use only Unicode letters, and -, ., \_, /, does not start or end with -, \_, or /, and does not allow trailing or consecutive -, \_, or /. | * JSON * Python SDK ``` "delivery": { "type": "s3_compatible", "parameters": { "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.subscription_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 a subscription using a destination, use the following delivery format: * JSON ``` "delivery": { "type": "destination", "parameters": { "ref": "pl:destinations/my-s3-destination-CKxV9io", "path_prefix": "planet-scenes" // optional path prefix } } ``` To create a subscription using the organization's default destination, specify the default alias: * JSON ``` "delivery": { "type": "destination", "parameters": { "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 subscriptions by their associated destination, use the `destination_ref` query parameter with the List Subscriptions endpoint: * CLI ``` curl -X GET "https://api.planet.com/subscriptions/v1?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 deliver 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 subscription name. If included, the collection must be compatible with the subscription, which will be validated during subscription 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 subscriptions with the same data type, first omit `collection_id` in your initial request to auto-create a collection. Then, use the returned `collection_id` for all subsequent requests. This links all subscriptions to the same collection efficiently. Importantly, subscriptions with different data types cannot share a collection. As an example, Soil Water Content and Land Surface Temperature subscriptions cannot share the same collection. #### No collection ID provided * JSON ``` "hosting": { "type": "sentinel_hub" } ``` #### Collection ID provided * JSON * Python SDK ``` "hosting": { "type": "sentinel_hub", "parameters": { "collection_id": "my_collection_id" } } ``` ``` from planet.subscription_request import sentinel_hub sh_delivery_collection = sentinel_hub(collection_id="my-collection-id") ``` Please note the following: * For imagery subscriptions the following tools are permitted: * [`harmonize`](https://docs.planet.com/develop/apis/subscriptions/tools.md#harmonize) * [`toar`](https://docs.planet.com/develop/apis/subscriptions/tools.md#top-of-atmosphere-reflectance-toar) * [`cloud_filter`](https://docs.planet.com/develop/apis/subscriptions/tools.md#cloud-filter) * The [`clip`](https://docs.planet.com/develop/apis/subscriptions/tools.md#clip) and [`file_format` (COG)](https://docs.planet.com/develop/apis/subscriptions/tools.md#file-format) tools are automatically added and cannot be removed * No tools are supported for [Planetary Variable](https://docs.planet.com/develop/apis/subscriptions/sources.md#planetary-variable-and-analysis-ready-source-types) subscriptions * After creation, only the [`cloud_filter`](https://docs.planet.com/develop/apis/subscriptions/tools.md#cloud-filter) tool can be added, modified, or removed; other tools cannot be changed 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 for [PlanetScope](https://docs.planet.com/data/imagery/planetscope.md) and [SkySat](https://docs.planet.com/data/imagery/skysat.md). The data will still be ingested, but may result in `nodata` pixels within the tile when requesting the imagery.