Imagery Delivery to GEE

You can use the Orders and Subscriptions API to deliver data to Google Earth Engine Image Collections.

The Orders API can be used to order data by specific item IDs and is best for one-time imagery orders.
The Subscriptions API can be used to order based on an area and time of interest and is best for ongoing delivery of new imagery or long times of interest.

Requirements

An existing Google Earth Engine Image Collection. You can create an Image Collection by using the Earth Engine code editor or the CLI.
For the Subscriptions API, you are required to provide a GEE service account which you will use in the credentials field for your requests.

Orders API Delivery

Delivery to Google Earth Engine (GEE) follows a similar structure as delivery to a cloud-storage bucket from the delivery to cloud storage.

Delivering to GEE requires that you already have the images and the image IDs. Use either the Data API, Planet Explorer, or a GIS integration to find the IDs for the images you want to order.

Supported Items and Assets

The Planet GEE Delivery supports the following items and product bundles.

Item Type	Supported Order Bundles	Limitations
PSScene	analytic_8b_sr_udm2, analytic_sr_udm2, analytic_8b_udm2, analytic_udm2, visual
SkySatScene	analytic, analytic_udm2, analytic_sr_udm2, visual, pansharpened_udm2, panchromatic_dn_udm2
SkySatCollect	analytic, analytic_udm2, analytic_sr_udm2, visual, pansharpened_udm2, panchromatic_dn_udm2	SkySatCollects can take as long as one hour per item to ingest.
Basemap Quads	NA	Without the merge tool, Basemaps are limited to 500 Quads per order. With the merge tool applied, Basemaps are limited to approximately 25 Quads per order.

Supported Tools

While many tools can be chained and used with various bundles, not all tools work well with all bundles and delivery destinations. The following table lists some of the tool constraints and limitations.

Tool	Supported Item Types	Limitations
Bandmath	PSScene, SkySatCollect, SkySatScene, Basemap Quads
Clip	PSScene, SkySatCollect, SkySatScene, Basemap Quads	Supported for all bundles except `basic_*`.
Harmonize	PSScene
Composite	PSScene, SkySatScene	Supported for all bundles except `basic_*`. All product inputs must share the same item type and bundle.
Coregister	PSScene, SkySatCollect, SkySatScene	Supported for all bundles except `basic_` and `_nitf`. Coregister is not compatible with the composite tool.
TOAR	PSScene, SkySatCollect, SkySatScene	Supported for the `analytic` bundle.
Reproject	PSScene, SkySatCollect, SkySatScene, Basemap Quads	Supported for all bundles except `basic_*`.
Tile	PSScene, SkySatCollect, SkySatScene	Not supported for GEE Delivery.
File Format	PSScene, SkySatCollect, SkySatScene	Not supported for GEE Delivery.
Merge	Basemap Quads	With merge applied, Basemap delivery is limited to approximately 25 Quads. One raster GeoTIFF is returned instead of the individual quads. Any assets, such as UDM, are also merged. The output files have _merge appended to the file names. The merged output must be less than 425 megapixels which is equal to the appoximate area of 25 Quads with 4096x4096 pixels. If the merge request exceeds 425 megapixels, the create order returns an error_hint containing the estimated pixel size of the attempted order.

Placing orders with unsupported tools in a delivery request results in the following response:

{
  "message": "Unable to accept order: GEE delivery does not support tools"
}

Create an Order

The following payload delivers PSScene analytic_8b_sr_udm2 images to the Planet GEE account. PSScene analytic_8b_sr_udm2 is an orders bundle type that delivers surface reflectance corrected PlanetScope images.

Specify the following two GEE fields in the delivery node:

Project
Collection Project

The fields must correspond to the GEE Cloud Project, and collection to the GEE Image Collection that will receive the images.

Simple delivery
Delivery with clip and harmonization

curl -X POST https://api.planet.com/compute/ops/orders/v2 \
  -H "Authorization: api-key PL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PSScene 8-band order Miami",
    "products": [
        {
        "item_ids": [
            "20220118_154923_68_2424"
        ],
        "item_type": "PSScene",
        "product_bundle": "analytic_8b_sr_udm2"
    }],
    "delivery":
    {
        "google_earth_engine": 
        {
            "project": "your-cloud-project-name",
            "collection": "your-image-collection-name"
        }
    },
    "notifications": 
    {
        "email": true
    }
}'

curl -X POST https://api.planet.com/compute/ops/orders/v2 \
  -H "Authorization: api-key PL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PSScene 8-band order Miami",
    "products": [
        {
            "item_ids": [
                "20220118_154923_68_2424"
                ],
        "item_type": "PSScene",
        "product_bundle": "analytic_8b_sr_udm2"
    }],
    "tools": [
        {
            "harmonize": 
                {
                "target_sensor": "Sentinel-2"
                }
    },{
        "clip": 
            {
            "aoi": 
                {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [-80.176302, 25.758621],
                            [-80.140075, 25.758621],
                            [-80.140075, 25.802288],
                            [-80.176302, 25.802288],
                            [-80.176302, 25.758621]
                        ]
                    ]
                }
            }
    }],
    "delivery": 
        {
        "google_earth_engine": 
            {
            "project": "your-cloud-project",
            "collection": "your-image-collection"
            }
    },
    "notifications": 
        {
        "email": true
        }
}'

Check Order Status

To check on order status, you can poll the Orders API with your order ID that is returned when you create the order. When the order status is Success, the images are available in your GEE image collection.

{
  "_links": {
    "_self": "https://ordersv2.next.prod.planet-labs.com/compute/ops/orders/v2/4711cf34-1e88-4d99-877c-a25d62418b64",
    "results": [
      {
        "delivery": "success",
        "expires_at": "2020-06-25T02:31:11.591Z",
        "location": "projects/your_cloud_project_name/assets/your_ee_image_collection_name/20180716_163210_103c_3B_AnalyticMS_SR",
        "name": "PSScene4Band/20180716_163210_103c_3B_AnalyticMS_SR.tif"
      },
      {
        "delivery": "success",
        "expires_at": "2020-06-25T02:32:02.502Z",
        "location": "projects/your_cloud_project_name/assets/your_ee_image_collection_name/20180716_162019_0f1a_3B_AnalyticMS_SR",
        "name": "PSScene4Band/20180716_162019_0f1a_3B_AnalyticMS_SR.tif"
      },
      {
        "delivery": "success",
        "expires_at": "2020-06-25T02:32:29.749Z",
        "location": "projects/your_cloud_project_name/assets/your_ee_image_collection_name/20180716_162016_0f1a_3B_AnalyticMS_SR",
        "name": "PSScene4Band/20180716_162016_0f1a_3B_AnalyticMS_SR.tif"
      },
      {
        "delivery": "success",
        "expires_at": "2020-06-25T02:32:56.820Z",
        "location": "projects/your_cloud_project_name/assets/your_ee_image_collection_name/20180716_163212_103c_3B_AnalyticMS_SR",
        "name": "PSScene4Band/20180716_163212_103c_3B_AnalyticMS_SR.tif"
      },
      {
        "delivery": "success",
        "expires_at": "2020-06-25T02:31:37.810Z",
        "location": "projects/your_cloud_project_name/assets/your_ee_image_collection_name/20180716_163213_103c_3B_AnalyticMS_SR",
        "name": "PSScene4Band/20180716_163213_103c_3B_AnalyticMS_SR.tif"
      },
      {
        "delivery": "success",
        "expires_at": "2020-06-25T02:31:25.155Z",
        "location": "projects/your_cloud_project_name/assets/your_ee_image_collection_name/20180716_163211_103c_3B_AnalyticMS_SR",
        "name": "PSScene4Band/20180716_163211_103c_3B_AnalyticMS_SR.tif"
      },
      {
        "delivery": "success",
        "expires_at": "2020-06-25T02:31:35.339Z",
        "location": "projects/your_cloud_project_name/assets/your_ee_image_collection_name/20180716_162018_0f1a_3B_AnalyticMS_SR",
        "name": "PSScene4Band/20180716_162018_0f1a_3B_AnalyticMS_SR.tif"
      },
      {
        "delivery": "success",
        "expires_at": "2020-06-25T02:32:19.476Z",
        "location": "projects/your_cloud_project_name/assets/your_ee_image_collection_name/20180716_162017_0f1a_3B_AnalyticMS_SR",
        "name": "PSScene4Band/20180716_162017_0f1a_3B_AnalyticMS_SR.tif"
      }
    ]
  },
  "created_on": "2020-06-24T02:27:30.935Z",
  "delivery": {
    "google_earth_engine": {
      "collection": "your_ee_image_collection_name",
      "project": "your_cloud_project_name"
    }
  },
  "error_hints": [],
  "id": "4711cf34-1e88-4d99-877c-a25d62418b64",
  "last_message": "Delivery completed",
  "last_modified": "2020-06-24T02:34:18.645Z",
  "name": "PS Cropland Delivery to GEE",
  "products": [
    {
      "item_ids": [
        "20180716_163213_103c",
        "20180716_163212_103c",
        "20180716_163211_103c",
        "20180716_163210_103c",
        "20180716_162019_0f1a",
        "20180716_162018_0f1a",
        "20180716_162017_0f1a",
        "20180716_162016_0f1a"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic_sr"
    }
  ],
  "state": "success"
}

Subscriptions API Delivery

Product Lifecyle: Beta

The Subscriptions API to Google Earth Engine delivery integration is currently in Beta.

The Subscriptions API now supports delivery to Google Earth Engine (GEE). This integration allows you to create a subscription that will automatically deliver new imagery to your GEE account as it becomes available. This integration works very similarly to the Orders API integration.

Supported Items and Assets

Item Types

All asset types are supported except basic_* assets.

Supported Tools

All tools are supported except for the NITF profile of file_format.

Create a Subscription

Below is a subscription request body with a standard source block and a GEE delivery block.

CURL

curl -X POST https://api.planet.com/subscriptions/v1/ \
  -H "Authorization: api-key PL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name" : "GEE Subscription",
    "source":
        {
        "type": "catalog",
        "parameters":
            {
            "asset_types": [
                "ortho_analytic_4b",
                "ortho_udm2",
                "ortho_visual"
            ],
            "item_types": [
                "PSScene"
            ],
            "geometry":
                {
                    "coordinates": [
                        [
                            [
                                139.5648193359375,
                                35.42374884923695
                            ],
                            [
                                140.1031494140625,
                                35.42374884923695
                            ],
                            [
                                140.1031494140625,
                                35.77102915686019
                            ],
                            [
                                139.5648193359375,
                                35.77102915686019
                            ],
                            [
                                139.5648193359375,
                                35.42374884923695
                            ]
                        ]
                    ],
                "type": "Polygon"
            },
            "start_time": "2023-09-08T00:00:00Z",
            "end_time": "2023-10-08T00:00:00Z"
        }
    },
    "delivery":
        {
            "type": "google_earth_engine",
            "parameters":
                {
                    "collection": "my-gee-collection",
                    "credentials": "<base_64_encoded_SA_key>",
                    "project": "my-gee-project"
                }
        }
    }'

Check Subscription Status

If your subscription source block matches some items in the Planet catalog, you'll soon receive some deliveries to earth engine. You can view the status of these deliveries by checking the subscription results endpoint.

Check subscription status
curl -X GET https://api.planet.com/subscriptions/v1/<subscription_id>/results/ \
  -H "Authorization: api-key PL_API_KEY" \
  -H "Content-Type: application/json" \

Subscription status response
[
  {
    "id": "c26ac3c6-e5bf-4625-b0ea-a0774d48a842",
    "status": "success",
    "properties": {
      "item_id": "20230912_003259_12_24b4",
      "item_types": ["PSScene"]
    },
    "created": "2023-09-18T18:57:13.615322Z",
    "updated": "2023-09-18T19:05:27.207838Z",
    "completed": "2023-09-18T19:05:27.207838Z",
    "errors": {},
    "outputs": [
      "3IY7YWR4YXJT3ABZQKEQLZUP (projects/my-gee-project/assets/my-gee-collection/20230912_003259_12_24b4_3B_AnalyticMS)",
      "DPU6EY4URKABCKPOZEDBJEBB (projects/my-gee-project/assets/my-gee-collection/20230912_003259_12_24b4_3B_Visual)"
    ]
  },
  {
    "id": "8ba9aca0-d1b8-476c-91aa-e781f0cec4da",
    "status": "success",
    "properties": {
      "item_id": "20230910_003337_52_2442",
      "item_types": ["PSScene"]
    },
    "created": "2023-09-18T18:57:13.615289Z",
    "updated": "2023-09-18T19:05:47.238997Z",
    "completed": "2023-09-18T19:05:47.238997Z",
    "errors": {},
    "outputs": [
      "YPOTBYMWG5CHMPZSOPQODBA5 (projects/my-gee-project/assets/my-gee-collection/20230910_003337_52_2442_3B_AnalyticMS)",
      "V52VP2VJSRMHSMBX3Q55YBRD (projects/my-gee-project/assets/my-gee-collection/20230910_003337_52_2442_3B_Visual)"
    ]
  }
]

If your results have the success status, that means that a GEE import task has been successfully initiated. That GEE task ID is the first part of each output string, followed by the GEE asset path. You can use the GEE task ID to check the status of the import task. See the notebook linked at the top of this page for a demonstration.

To view your subscriptions or monitor their statuses, please refer to the Subscriptions API documentation.

Using Service Accounts

note

Important: When creating an order, you must input your credentials for successful delivery of Planet data to cloud storage. This introduces a potential security risk. For secure delivery to cloud storage, limit access to the required delivery path without read/write access for any other storage locations or cloud services.

You can use your own Google service account to deliver images to Google Earth Engine. Using your Google service account provides you with a dedicated queue for orders. When using the default service account from Planet, the queue is shared among orders and can result in a delay. Each service account has a queue depth limit of approximately 3,000 when delivering to Google Earth Engine.

To write to an EE account, the Planet Google service account must have the EE Resource Writer IAM role. The Resource Writer role provides read/write access to an EE Cloud Project. Create a separate Cloud Project account without Read access for sensitive or proprietary data.

Planet recommends a limit of approximately 1000 assets delivered per organization, per day, when using the shared queue. Beyond this, we recommend that you use your own service account.

You can read more about this in the Google documentation for managing service accounts.
Enroll your SA to Earth Engine by using the sign up page.

Orders with service account
curl -X POST https://api.planet.com/compute/ops/orders/v2 \
  -H "Authorization: api-key PL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Miami 8-band Image - BYOS",
    "products": [
        {
            "item_ids": [
                "20220118_154923_68_2424"
            ],
            "item_type": "PSScene",
            "product_bundle": "analytic_8b_sr_udm2"
        }
    ],
    "delivery":
        {
            "google_earth_engine":
                {
                    "project": "your_cloud_project_name",
                    "collection": "your_ee_image_collection_name",
                    "credentials": "<base64 credential>"
                }
        }
}'

note

Planet recommends using a command line tool such as base64 to encode your credentials. Avoid using online tools that can expose your credentials.

Using Planet Data in GEE

The following are example code snippets that you can use while working with Planet data in Google Earth Engine.

True Color

True color
Map.addLayer(imageCollection, {"opacity":1,"bands":["B6","B4","B2"],"min":405.79,"max":4499.71,"gamma":2.331})

False Color Infrared

False color infrared
Map.addLayer(imageCollection, {"opacity":1,"bands":["B8","B4","B6"],"min":405.79,"max":4499.71,"gamma":2.331})

NDVI

NDVI
Map.addLayer(image.normalizedDifference(["B8", "B6"]).rename("NDVI"), {min: -1, max: 1, palette: ["blue", "white", "green"]});

Usable Data Mask

Ordering a Planet analytic_sr_udm2 appends the Usable Data Mask (UDM) bands to PlanetScope images.

Usable Data Mask
Map.addLayer(image.select("Q8"), {min: 0, max: 1, palette: ["black", "white"]});

More Resources

📖

Planet and Google Earth Engine Python Notebook

Get started with Planet data in Google Earth Engine using Python.

Requirements​

Orders API Delivery​

Supported Items and Assets​

Supported Tools​

Create an Order​

Check Order Status​

Subscriptions API Delivery​

Supported Items and Assets​

Supported Tools​

Create a Subscription​

Check Subscription Status​

Using Service Accounts​

Using Planet Data in GEE​

True Color​

False Color Infrared​

NDVI​

Usable Data Mask​

More Resources​

Planet and Google Earth Engine Python Notebook

Requirements

Orders API Delivery

Supported Items and Assets

Supported Tools

Create an Order

Check Order Status

Subscriptions API Delivery

Supported Items and Assets

Supported Tools

Create a Subscription

Check Subscription Status

Using Service Accounts

Using Planet Data in GEE

True Color

False Color Infrared

NDVI

Usable Data Mask

More Resources