Copy for LLM[View as Markdown](https://docs.planet.com/platform/integrations/google-earth-engine/order-imagery-gee/) # 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](https://developers.google.com/earth-engine/ic_creating). 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](#using-service-accounts) 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](https://docs.planet.com/develop/apis/orders/delivery.md#delivery-to-cloud-storage). Delivering to GEE requires that you already have the images and the image IDs. Use either the [Data API](https://docs.planet.com/develop/apis/data.md), [Planet Explorer](https://www.planet.com/explorer), or a [GIS integration](https://docs.planet.com/platform/integrations.md) 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](https://docs.planet.com/develop/apis/orders/product_bundles.md). | Item Type | Supported Order Bundles | Limitations | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | [PSScene](https://docs.planet.com/data/imagery/planetscope.md) | analytic\_8b\_sr\_udm2, analytic\_sr\_udm2, analytic\_8b\_udm2, analytic\_udm2, visual | | | [SkySatScene](https://docs.planet.com/data/imagery/skysat/item-types/skysatscene.md) | analytic, analytic\_udm2, analytic\_sr\_udm2, visual, pansharpened\_udm2, panchromatic\_dn\_udm2 | | | [SkySatCollect](https://docs.planet.com/data/imagery/skysat/item-types/skysatcollect.md) | analytic, analytic\_udm2, analytic\_sr\_udm2, visual, pansharpened\_udm2, panchromatic\_dn\_udm2 | SkySatCollects can take as long as one hour per item to ingest. | | [Mosaic Quads](https://docs.planet.com/data/imagery/mosaics.md) | NA | Without the merge tool, Mosaics are limited to 500 Quads per order. With the merge tool applied, Mosaics 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](https://docs.planet.com/develop/apis/orders/tools.md#band-math) | PSScene, SkySatCollect, SkySatScene, Mosaic Quads | | | [Clip](https://docs.planet.com/develop/apis/orders/tools.md#clip) | PSScene, SkySatCollect, SkySatScene, Mosaic Quads | Supported for all bundles except `basic_*`. | | [Harmonize](https://docs.planet.com/develop/apis/orders/tools.md#harmonize) | PSScene | | | [Composite](https://docs.planet.com/develop/apis/orders/tools.md#composite) | PSScene, SkySatScene | Supported for all bundles except `basic_*`. All product inputs must share the same item type and bundle. | | [Coregister](https://docs.planet.com/develop/apis/orders/tools.md#coregister) | PSScene, SkySatCollect, SkySatScene | Supported for all bundles except `basic_*` and `*_nitf`. Coregister is not compatible with the composite tool. | | [TOAR](https://docs.planet.com/develop/apis/orders/tools.md#top-of-atmosphere-reflectance-toar) | PSScene, SkySatCollect, SkySatScene | Supported for the `analytic` bundle. | | [Reproject](https://docs.planet.com/develop/apis/orders/tools.md#reproject) | PSScene, SkySatCollect, SkySatScene, Mosaic Quads | Supported for all bundles except `basic_*`. | | [Tile](https://docs.planet.com/develop/apis/orders/tools.md#tile) | PSScene, SkySatCollect, SkySatScene | Not supported for GEE Delivery. | | [File Format](https://docs.planet.com/develop/apis/orders/tools.md#file-format) | PSScene, SkySatCollect, SkySatScene | Not supported for GEE Delivery. | | [Merge](https://docs.planet.com/develop/apis/orders/tools.md#merge) | Mosaic Quads | With merge applied, mosaic 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 * [PSScene](https://docs.planet.com/data/imagery/planetscope/psscene.md) * [SkySatScene](https://docs.planet.com/data/imagery/skysat/item-types/skysatscene.md) * [SkySatCollect](https://docs.planet.com/data/imagery/skysat/item-types/skysatcollect.md) 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": { "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": "", "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//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](https://docs.planet.com/develop/apis/subscriptions.md). ## 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](https://cloud.google.com/iam/docs/creating-managing-service-accounts). * Enroll your SA to Earth Engine by using the [sign up page](https://signup.earthengine.google.com/#!/service_accounts). 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": "" } } }' ``` 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)](https://docs.planet.com/data/imagery/udm.md) bands to PlanetScope images. Usable Data Mask ``` Map.addLayer(image.select("Q8"), {min: 0, max: 1, palette: ["black", "white"]}); ``` ## Additional Resources [đź“–Planet and Google Earth Engine Python Notebook](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/workflows/google_earth_engine_integration/gee_integration_orders.ipynb) [Get started with Planet data in Google Earth Engine using Python.](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/workflows/google_earth_engine_integration/gee_integration_orders.ipynb)