Skip to main content

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 section.

The examples below use Google Cloud Storage.

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}"'"   
            }
        }
    }'

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 -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"
            }
        ]
    }'

Image collection​

Results can be hosted on the platform using the hosting block. More information on hosting can be found in the Delivery section. If no collection_id is provided, one will be created on your behalf and the ID will be returned in the response.

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": {}
        }
    }'

Example: Create Basemaps Order​

The following basemaps order requests are ordering the mosaic global_monthly_2022_01_mosaic.

By geometry​

The following examples use direct download (not cloud storage).

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]
                        ]
                    ]
                }
            }
        ]
    }'

By quad IDs​

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"
                ]
            }
        ]
    }'

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 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 -X GET https://api.planet.com/compute/ops/orders/v2/${ORDER_ID} \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

The response schema can be found in the API Reference.

Download Order​

You can download the output of an order by following the location urls in the order's GET response (see 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 -L -X GET "$LOCATION" > download.tif

Example: Download All Assets from an Order​

The Python SDK and Planet CLI support downloading all assets in an order in a single call.

from planet import Planet

pl = Planet()


def download_order(order_id):
    paths = pl.orders.download_order(order_id)
    return paths

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 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.

Example: List Orders​

All orders created by the requester​

curl -X GET https://api.planet.com/compute/ops/orders/v2 \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

Filtering orders by state, created_on, hosting, and sorting by created_on​

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"

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/<order_id>

Example: Cancel Order​

The following examples assume you have an order ID exported as an environment variable ORDER_ID.

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"

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.

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 -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 '{}'
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 -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}"'"
        ]
    }'

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 -X GET https://api.planet.com/compute/ops/stats/orders/v2 \
    -H "Authorization: api-key $PL_API_KEY" \
    -H "Content-Type: application/json"

The response schema can be found in the API Reference.

Last updated on