Ordering and Delivering to Google Earth Engine¶
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 Planet Data API, Planet Explorer, or either of the Planet GIS integrations. To use the integrations, your organization must have download quota. To set up plan with an appropriate amount of download quota, Contact Sales.
Also, the GEE Image Collection being delivered must already exist. Create an Image Collection by using the Earth Engine code editor or the CLI.
Supported Item and Asset Types¶
| 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. |
See Items and Assets for more information.
Supported Raster Operations¶
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"
}
Example GEE delivery payloads¶
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.
The Orders REST URL¶
https://api.planet.com/compute/ops/orders/v2
Simple delivery¶
{
"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
}
}
Delivery with clip and harmonization applied¶
{
"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
}
}
Example GEE delivery response¶
Example API response¶
{
"_links": {
"_self": "https://api.planet.com/compute/ops/orders/v2/9aedcc50-6e29-4880-8dcf-7f168214cca3"
},
"created_on": "2022-02-01T23:04:14.251Z",
"delivery": {
"google_earth_engine": {
"collection": "your-image-collection",
"credentials": "<REDACTED>",
"project": "your-cloud-project"
}
},
"error_hints": [],
"id": "9aedcc50-6e29-4880-8dcf-7f168214cca3",
"last_message": "Preparing order",
"last_modified": "2022-02-01T23:04:14.251Z",
"name": "PSScene 8-band order Miami",
"notifications": {
"email": true
},
"products": [
{
"item_ids": [
"20220118_154923_68_2424"
],
"item_type": "PSScene",
"product_bundle": "analytic_8b_sr_udm2"
}
],
"state": "queued",
"tools": [
{
"harmonize": {
"target_sensor": "Sentinel-2"
}
},
{
"clip": {
"aoi": {
"coordinates": [
[
[
-80.176302,
25.758621
],
[
-80.140075,
25.758621
],
[
-80.140075,
25.802288
],
[
-80.176302,
25.802288
],
[
-80.176302,
25.758621
]
]
],
"type": "Polygon"
}
}
}
]
}
Delivery success¶
To check on order status, pull the URL in the API response that was provided after order submission. When the order status is Success, the images are available in your GEE image collection. If required, refresh the GEE assets to view the new images.
{
"\_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"
}
Use a Google Service Account¶
Imprortant: 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.
Use your own Google Service Account (SA) to deliver images to GEE. Using your Google SA, provides a dedicated queue for orders. When using the default SA from Planet, orders compete with other orders in the queue. Each SA has approximately 3000 queue depth limit when delivering to GEE.
Creating a Service Account¶
Managing Service Accounts provides more details.
Considerations:
- Enroll your SA to Earth Engine by using the sign up page
- Assign GEE Writer IAM Roles to your Service Account. See Step 3 for more details
Using your Service Account¶
To submit your GEE Delivery Order with your own Service Account, add a new credentials field to your payload.
{
"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>"
}
}
}
Important: Planet recommends using a command line tool such as base64 to encode your credentials. Avoid using online tools that can expose your credentials.
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.