Copy for LLM[View as Markdown](https://docs.planet.com/develop/apis/orders/mechanics/) # Mechanics ## Create an Order You can create an order by submitting a HTTP POST request to the following endpoint: ``` POST https://api.planet.com/compute/ops/orders/v2 ``` The order request must include `name`, `source_type`, and `products` parameters. Optionally, you can include `delivery`, `notifications`, and `tools` parameters. If no `delivery` block is provided, download links will be generated and available through a `GET` request for the created order. ### Example: Create Scenes Order The following scenes order request is ordering two items, of the `PSScene` item type, and the `analytic_udm2` product bundle. For each item, the output assets will be `ortho_analytic_4b`, `ortho_analytic_4b_xml`, and `ortho_udm2`. The clip tool is also applied in some examples, which will clip the requested items to the provided geometry. #### Cloud delivery If a `delivery` block is specified, the order results will be delivered to the specified cloud storage location. More information on cloud storage destinations can be found in the [Delivery](https://docs.planet.com/develop/apis/orders/delivery.md#delivery-to-cloud-storage) section. The examples below use [Google Cloud Storage](https://docs.planet.com/develop/apis/orders/delivery.md#google-cloud-storage). * CURL * Python SDK * CLI ``` 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": "scenes order, gcs cloud storage", "source_type": "scenes", "products": [ { "item_ids": [ "20220304_093300_37_2430", "20220305_093440_25_2429" ], "item_type": "PSScene", "product_bundle": "analytic_udm2" } ], "tools": [ "clip": { "aoi": { "type": "Polygon", "coordinates": [ [ [6.32968245, 45.82695668], [6.32968294, 45.81749065], [6.34141363, 45.81749011], [6.34141312, 45.82695623], [6.32968245, 45.82695668], ] ] } } ] "delivery": { "google_cloud_storage": { "bucket": "'"${GCS_BUCKET}"'", "credentials": "'"${GCS_CREDENTIALS}"'" } } }' ``` ``` from planet import Planet from planet.order_request import ( build_request, clip_tool, google_cloud_storage, product, ) pl = Planet() def create_gcs_scene_order(gcs_bucket, gcs_credentials): gcs_delivery = google_cloud_storage( bucket=gcs_bucket, credentials=gcs_credentials, ) clip = clip_tool( { "type": "Polygon", "coordinates": [ [ [6.32968245, 45.82695668], [6.32968294, 45.81749065], [6.34141363, 45.81749011], [6.34141312, 45.82695623], [6.32968245, 45.82695668], ] ], } ) request = build_request( name="scenes order, gcs cloud storage", products=[ product( item_ids=[ "20220304_093300_37_2430", "20220305_093440_25_2429", ], product_bundle="analytic_udm2", item_type="PSScene", ) ], tools=[clip], delivery=gcs_delivery, ) order = pl.orders.create_order(request) return order ``` ``` geometry="{ \"type\": \"Polygon\", \"coordinates\": [ [ [6.32968245, 45.82695668], [6.32968294, 45.81749065], [6.34141363, 45.81749011], [6.34141312, 45.82695623], [6.32968245, 45.82695668], ] ] }" delivery="{ \"google_cloud_storage\": { \"bucket\": \"${GCS_BUCKET}\", \"credentials\": \"${GCS_CREDENTIALS}\" } }" planet orders request \ --item-type PSScene \ --bundle analytic_udm2 \ --name 'scenes order, gcs cloud storage' \ --clip "$geometry" \ --delivery "$delivery" \ 20220304_093300_37_2430,20220305_093440_25_2429 \ | planet orders create - ``` #### Direct download If no `delivery` block is specified, the order results will be available through signed URLs for direct download. These URLs will populate on the `GET` response as the order processes. It is recommended to wait until the order is in a `success` state before downloading order results. * CURL * Python SDK * CLI ``` 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": "scenes order, direct download", "source_type": "scenes", "products": [ { "item_ids": [ "20220304_093300_37_2430", "20220304_093257_90_2430" ], "item_type": "PSScene", "product_bundle": "analytic_udm2" } ] }' ``` ``` from planet import Planet from planet.order_request import ( build_request, product, ) pl = Planet() def create_direct_download_scene_order(): request = build_request( name="scenes order, direct download", products=[ product( item_ids=[ "20220304_093300_37_2430", "20220304_093257_90_2430", ], product_bundle="analytic_udm2", item_type="PSScene", ) ], ) order = pl.orders.create_order(request) return order ``` ``` planet orders request \ --item-type PSScene \ --bundle analytic_udm2 \ --name 'scenes order, direct download' \ 20220304_093300_37_2430,20220304_093257_90_2430 \ | planet orders create - ``` #### Data collection Results can be hosted on Planet Insights Platform using the hosting block. More information on hosting can be found in the [Delivery](https://docs.planet.com/develop/apis/orders/delivery.md#delivery-layout) section. If no `collection_id` is provided, one will be created on your behalf and the ID will be returned in the response. * CURL * Python SDK * CLI ``` 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": "scenes order, hosting", "source_type": "scenes", "products": [ { "item_ids": [ "20220304_093300_37_2430", "20220304_093257_90_2430" ], "item_type": "PSScene", "product_bundle": "analytic_udm2" } ], "hosting": { "sentinel_hub": {} } }' ``` ``` from planet import Planet from planet.order_request import build_request, product pl = Planet() def create_hosting_scene_order(): request = build_request( name="scenes order, hosting", products=[ product( item_ids=[ "20220304_093300_37_2430", "20220304_093257_90_2430", ], product_bundle="analytic_udm2", item_type="PSScene", ) ], hosting="sentinel_hub", ) order = pl.orders.create_order(request) return order ``` ``` planet orders request \ --item-type PSScene \ --bundle analytic_udm2 \ --name 'scenes order, hosting' \ --hosting sentinel_hub \ 20220304_093300_37_2430,20220304_093257_90_2430 \ | planet orders create - ``` ### Example: Create Mosaics Order The following mosaics order requests are ordering the mosaic `global_monthly_2022_01_mosaic`. #### By geometry The following examples use direct download (not cloud storage). * CURL * CLI ``` 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": "basemap order, by geometry, direct download", "source_type": "basemaps", "products": [ { "mosaic_name": "global_monthly_2022_01_mosaic", "geometry": { "type": "Polygon", "coordinates":[ [ [4.607406, 52.353994], [4.680005, 52.353994], [4.680005, 52.395523], [4.607406, 52.395523], [4.607406, 52.353994] ] ] } } ] }' ``` ``` planet orders create '{ "name": "basemaps order, by geometry, direct download", "source_type": "basemaps", "products": [ { "mosaic_name": "global_monthly_2022_01_mosaic", "geometry": { "type": "Polygon", "coordinates":[ [ [4.607406, 52.353994], [4.680005, 52.353994], [4.680005, 52.395523], [4.607406, 52.395523], [4.607406, 52.353994] ] ] } } ] }' ``` #### By quad IDs * CURL * CLI ``` 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": "basemap order, by quad ids, direct download", "source_type": "basemaps", "products": [ { "mosaic_name": "global_monthly_2022_01_mosaic", "quad_ids": [ "1050-1374", "1050-1375" ] } ] }' ``` ``` planet orders create '{ "name": "basemaps order, by quad ids, direct download", "source_type": "basemaps", "products": [ { "mosaic_name": "global_monthly_2022_01_mosaic", "quad_ids": [ "1050-1374", "1050-1375" ] } ] }' ``` ## Get Order You can get the details of an order by submitting a HTTP GET request to the following endpoint: ``` GET https://api.planet.com/compute/ops/orders/v2/{order-id} ``` The response schema will include the original order request and timestamp, order state, error hints, last message, last update timestamp, and an array of results. * `error_hints`: Human readable details which may provide insights to why an order failed. These descriptions may change; do not build on these values. * `last_message`: Human readable details on sub-state processing. These descriptions may change; do not build on these values. * `last_modified`: Timestamp of the order’s last sub-state processing step. Modification sequencing may change; do not build on these values. * `results`: The outputs of the order; resulting output will vary depending on raster tools and/or zip applied. * `delivery`: Delivery status: success or failed. * `name`: File path of the output; see the [Delivery page](https://docs.planet.com/develop/apis/orders/delivery.md#delivery-layout) for more details on delivery layouts. * `expires_at`: Timestamp after which the order's download URL must be refreshed for a successful download. To refresh a download link send another GET Order request. * `location`: A link to download the output if a cloud delivery or hosting is not used. ### Example: Get Order The following examples assume you have an order ID exported as an environment variable `ORDER_ID`. * CURL * Python SDK * CLI ``` curl -X GET https://api.planet.com/compute/ops/orders/v2/${ORDER_ID} \ -H "Authorization: api-key $PL_API_KEY" \ -H "Content-Type: application/json" ``` ``` from planet import Planet pl = Planet() def get_order(order_id): order = pl.orders.get_order(order_id) return order ``` ``` planet orders get ${ORDER_ID} ``` The response schema can be found in the [API Reference](https://docs.planet.com/develop/apis/orders/reference.md#tag/Orders/operation/getOrder). ## Download Order You can download the output of an order by following the `location` urls in the order's `GET` response (see [Get Order](https://docs.planet.com/develop/apis/orders/mechanics.md#get-order)). When following the pregenerated download links, no authentication is required as the token generated in the `GET` request is valid for a limited time. ``` GET https://api.planet.com/compute/ops/download/?token=... ``` ### Example: Download an Asset from an Order The environment variable `LOCATION` in the example below represents the `location` field in the order's `GET` response for the desired asset. * CURL * Python SDK ``` curl -L -X GET "$LOCATION" > download.tif ``` ``` from planet import Planet pl = Planet() def download_asset(location): path = pl.orders.download_asset(location) return path ``` ### Example: Download All Assets from an Order The Python SDK and Planet CLI support downloading all assets in an order in a single call. * Python SDK * CLI ``` from planet import Planet pl = Planet() def download_order(order_id): paths = pl.orders.download_order(order_id) return paths ``` ``` planet orders download ${ORDER_ID} ``` ## List Orders You can list all orders created with your API key by submitting a HTTP GET request to the following endpoint: ``` GET https://api.planet.com/compute/ops/orders/v2 ``` Only orders created within the last three months will be returned. You can [submit a request](https://support.planet.com/hc/en-us/requests/new) for inquiries about orders placed more than three months ago. ### Query Parameters The list endpoint supports filtering on a number of order properties such as `state`, `source_type`, `created_on`, and `last_modified` to name a few. The full set of properties with examples can be found in the [API Reference](https://docs.planet.com/develop/apis/orders/reference.md#tag/Orders/operation/listOrders). If you are an organization administrator, you can use the `user_id` query parameter to list orders created by other users in your organization. List all orders using `user_id=all`, or orders made by a specific user in your organization by providing their user ID. ### Example: List Orders #### All orders created by the requester * CURL * Python SDK * CLI ``` curl -X GET https://api.planet.com/compute/ops/orders/v2 \ -H "Authorization: api-key $PL_API_KEY" \ -H "Content-Type: application/json" ``` ``` from planet import Planet pl = Planet() def list_orders(): orders = pl.orders.list_orders() return orders ``` ``` planet orders list ``` #### Filtering orders by state, created\_on, hosting, and sorting by created\_on * CURL * Python SDK * CLI ``` curl -X GET "https://api.planet.com/compute/ops/orders/v2?state=success&created_on=../2024-01-01T00:00:00.00Z&hosting=false&sort_by=created_on%20DESC" \ -H "Authorization: api-key $PL_API_KEY" \ -H "Content-Type: application/json" ``` ``` from planet import Planet pl = Planet() def list_filtered_orders(): orders = pl.orders.list_orders( state="success", created_on="../2024-01-01T00:00:00.00Z", hosting=False, sort_by="created_on DESC", ) return orders ``` ``` planet orders list \ --state success \ --created-on ../2024-01-01T00:00:00.00Z \ --hosting false \ --sort-by "created_on DESC" ``` ## Cancel Order Orders may be cancelled while they are in a `queued` state. After an order has moved into a `running` state, it may no longer be cancelled. You can cancel an order by submitting a HTTP PUT request to the following endpoint: ``` PUT https://api.planet.com/compute/ops/orders/v2/ ``` ### Example: Cancel Order The following examples assume you have an order ID exported as an environment variable `ORDER_ID`. * CURL * Python SDK * CLI ``` curl -X PUT https://api.planet.com/compute/ops/orders/v2/${ORDER_ID} \ -H "Authorization: api-key $PL_API_KEY" -H "Content-Type: application/json" ``` ``` from planet import Planet pl = Planet() def cancel_order(order_id): cancelled_order = pl.orders.cancel_order(order_id) return cancelled_order ``` ``` planet orders cancel ${ORDER_ID} ``` ## Cancel Orders in Bulk The Orders API supports two bulk order cancellation approaches: 1. Bulk cancel all queued orders 2. Bulk cancel a specified list of `order_ids` Both approaches should submit a POST request to the following endpoint: ``` POST https://api.planet.com/compute/ops/orders/v2/cancel ``` The response will include a count of orders which were successfully cancelled and which failed to cancel and why. The response schema can be found in the [API Reference](https://docs.planet.com/develop/apis/orders/reference.md#tag/Orders/operation/bulkCancelOrders). ### Example: Bulk Cancel Queued Orders All queued orders can be cancelled by submitting a HTTP POST request with an empty JSON object in the body. * CURL * Python SDK ``` curl -X POST https://api.planet.com/compute/ops/bulk/orders/v2/cancel \ -H "Authorization: api-key $PL_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` ``` from planet import Planet pl = Planet() def bulk_cancel_queued_orders(): response = pl.orders.cancel_orders() return response ``` note Because of the asynchronous nature of the Planet ordering system, some of the orders in a `queued` state at the time of the request may transition to a `running` state as we service the request and may no longer be cancellable. As such, it cannot be guaranteed that all orders queued at the time of the request will be successfully cancelled. ### Example: Bulk Cancel Orders by `order_ids` You can cancel a set of orders by submitting a HTTP POST request with a JSON object containing a list of `order_ids` in the body. The following examples assume you have an two order IDs exported as environment variables `ORDER_ID_1` and `ORDER_ID_2`. * CURL * Python SDK ``` curl -X POST https://api.planet.com/compute/ops/bulk/orders/v2/cancel \ -H "Authorization: api-key $PL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "order_ids": [ "'"${ORDER_ID_1}"'", "'"${ORDER_ID_2}"'" ] }' ``` ``` from planet import Planet pl = Planet() def bulk_cancel_by_order_ids(order_ids): response = pl.orders.cancel_orders(order_ids) return response ``` ## Aggregated Order Stats You can get aggregated statistics for orders by organization and user by submitting a HTTP GET request to the following endpoint: ``` GET https://api.planet.com/compute/ops/stats/orders/v2 ``` The response schema will include counts of orders in `running` and `queued` states for the requester and the requester's organization to give context on queue depth and throughput. ### Example: Aggregated Order Stats * CURL * Python SDK ``` curl -X GET https://api.planet.com/compute/ops/stats/orders/v2 \ -H "Authorization: api-key $PL_API_KEY" \ -H "Content-Type: application/json" ``` ``` from planet import Planet pl = Planet() def get_stats(): stats = pl.orders.aggregated_order_stats() return stats ``` The response schema can be found in the [API Reference](https://docs.planet.com/develop/apis/orders/reference.md#tag/Orders/operation/getSpec).