Ordering Scenes

last updated: March 18, 2024

Basic Ordering

A scene is a single logical observation captured by a satellite. A scenes order in the Orders API includes a source type, a set of item ids, an item type, and a product bundle–a predefined set of imagery and metadata assets.

  • source_type: is the product you are choosing to order. The choices are scenes or basemap. All orders, except for basemaps, are scenes source types.
  • item_ids: represent the catalog items of the scenes you wish to download. You can find the item_ids of the items you wish to download by creating a search in the Data API or Planet Explorer. Note: item_ids ending in the following characters are items from test satellites and may not have the full range of associated assets: (0f02, 0f06, 0f4c, 1055).
  • item_type: represents the sensors and processing characteristics of a catalog item. Example item types include PSScene and SkySatCollect. You can read more about item types on our Imagery Reference page.
  • product_bundles: are scenes-specific concept which group sets of asset_types together for more streamlined ordering. A valid product bundle for a set of items depends on their item type. An item is only delivered for an order if all assets in its specified product bundle are available. You can read more about scene assets on our Imagery Reference page and more about product bundles on our Product Bundle Reference page.

Example Request

POST https://api.planet.com/compute/ops/orders/v2

{
   "name":"simple order",
   "source_type": "scenes",
   "products":[
      {
         "item_ids":[
            "20220304_093300_37_2430",
            "20220304_093257_90_2430",
            "20220304_103324_1105",
            "20220304_103325_1105"
         ],
         "item_type":"PSScene",
         "product_bundle":"analytic_udm2"
      }
   ]
}

Example Response

{
    "_links": {
        "_self": "https://api.planet.com/compute/ops/orders/v2/98d124c3-0857-49f5-aa1b-2250c6f907ed"
    },
    "created_on": "2022-11-16T02:54:43.824Z",
    "error_hints": [],
    "id": "98d124c3-0857-49f5-aa1b-2250c6f907ed",
    "last_message": "Preparing order",
    "last_modified": "2022-11-16T02:54:43.824Z",
    "name": "simple order",
    "products": [
        {
            "item_ids": [
                "20220304_093300_37_2430",
                "20220304_093257_90_2430",
                "20220304_103324_1105",
                "20220304_103325_1105"
            ],
            "item_type": "PSScene",
            "product_bundle": "analytic_udm2"
        }
    ],
    "source_type": "scenes",
    "state": "queued"
}

Order Type and Fallback Bundles

The Orders API supports two order types: full and partial.

full Order Type

By default, if unspecified, all orders have an order_type of full. A full order type will fail an order if complete product bundles (with all required asset_types) are not available for all items included in the order. This is not uncommon for analytic_sr bundles, due to the publishing delay for analytic_sr assets, as well as for *_udm2 bundles, due to intermittent availability of udm2 assets before July 2018.

To avoid this issue (especially for analytic_sr product bundles), we recommend using the AssetFilter search feature in the Data API to ensure that all items supplied to the Orders API have all the required assets in the specified product bundle.

A full order type will also fail if:

  • The requester lacks permissions to access any of the required asset_types in the product_bundle
  • The requester lacks permissions to access any of the order’s specified item_types
  • The requester lacks permissions to access any of the specified item_ids due to geometry or time of interest policy restrictions

partial Order Type

A partial order type will deliver product bundles for all items included in the order which have all the complete product bundles (all required asset_types). In the analytic_udm2 product bundle example provided above, a partial order would deliver all the items in the order which have all analytic_udm2 assets, and omit delivery of items which are missing any of the required assets.

A partial order type will also omit delivery of items which the requester lacks permissions to access and provide error hints for items which failed to deliver, as long as at least one item bundle is deliverable.

An important note here is that the Orders API will always deliver all or none of the assets in the product bundle for an item. It will never deliver partial product bundles – only partial orders, with complete product bundles for the items which were delivered.

Example Request

POST https://api.planet.com/compute/ops/orders/v2

{
   "name": "partial simple order",
   "source_type": "scenes",
   "order_type": "partial",
   "products":[
      {
         "item_ids":[
            "20220304_093300_37_2430",
            "20220304_093257_90_2430",
            "20220304_103324_1105",
            "20220304_103325_1105"
         ],
         "item_type": "PSScene",
         "product_bundle": "analytic_udm2"
      }
   ]
}

Fallback Bundles

A "fallback" bundle is a product bundle that the Orders API will deliver if the first choice product bundle fails for any reason (asset availability, permissions, etc.). As an example, a fallback bundle could be used to deliver an analytic_udm2 bundle for an item, if all the assets in the analytic_8b_udm2 bundle are not available.

To specify a fallback bundle simply add the alternate bundle(s) to the product_bundle field separated by commas.

Example Request

POST https://api.planet.com/compute/ops/orders/v2

{
   "name":"fallback order",
   "source_type": "scenes",
   "products":[
      {
         "item_ids":[
            "20220304_093300_37_2430",
            "20220304_093257_90_2430",
            "20220304_103324_1105",
            "20220304_103325_1105"
         ],
         "item_type":"PSScene",
         "product_bundle":"analytic_8b_udm2,analytic_udm2"
      }
   ]
}

Ordering Multiple Item Types

To order items of multiple item_types, you can add another products set within the array of the products block.

Note

Different item types (such as PlanetScope or SkySat) can be included in the same order. Item types can be ordered as long as there is a plan that enables access to all of those item types.

Example Request

POST https://api.planet.com/compute/ops/orders/v2

{
   "name":"multiple_item_type_order",
   "source_type": "scenes",
   "products":[
      {
         "item_ids":[
            "20220306_094818_22_2276","20220306_094815_93_2276"
         ],
         "item_type":"PSScene",
         "product_bundle":"analytic_udm2"
      },
      {
        "item_ids": [
            "20171226_222055_6021709_RapidEye-3"
        ],
        "item_type": "REOrthoTile",
        "product_bundle": "analytic"
  }
   ]
}

Please submit a request with any questions about your quota or Admin Subscriptions.

Get an Order

You can get the status and results of your order, with the following request:

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: lists human readable details which may provide insights to why an order failed. These descriptions may change; do not build on these values.
  • last_message: lists human readable details on sub-state processing. These descriptions may change; do not build on these values.
  • last_modified: lists a timestamp on the order’s last sub-state processing step. Modification sequencing may change; do not build on these values.
  • results: lists the outputs of the order; results may look different depending raster and zip tools applied
    • delivery: “success” or "failed"
    • name: file path of the output; see our 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 is not used

Example Request

GET https://api.planet.com/compute/ops/orders/v2/d4c52078-0935-4255-aafd-c889726b5a9c

Example Response

{
    "_links": {
        "_self": "https://api.planet.com/compute/ops/orders/v2/d4c52078-0935-4255-aafd-c889726b5a9c",
        "results": [
            {
                "delivery": "success",
                "expires_at": "2022-11-17T03:27:11.487Z",
                "location": "[DOWNLOAD_URL]",
                "name": "d4c52078-0935-4255-aafd-c889726b5a9c/PSScene/20220304_103325_1105_3B_udm2.tif"
            },
            {
                "delivery": "success",
                "expires_at": "2022-11-17T03:27:11.496Z",
                "location": "[DOWNLOAD_URL]",
                "name": "d4c52078-0935-4255-aafd-c889726b5a9c/PSScene/20220304_103325_1105_metadata.json"
            },
            {
                "delivery": "success",
                "expires_at": "2022-11-17T03:27:11.499Z",
                "location": "[DOWNLOAD_URL]",
                "name": "d4c52078-0935-4255-aafd-c889726b5a9c/PSScene/20220304_093257_90_2430_3B_udm2.tif"
            },
            {
                "delivery": "success",
                "expires_at": "2022-11-17T03:27:11.508Z",
                "location": "[DOWNLOAD_URL]",
                "name": "d4c52078-0935-4255-aafd-c889726b5a9c/PSScene/20220304_093257_90_2430_metadata.json"
            },
            .
            .
            .
            {
                "delivery": "success",
                "expires_at": "2022-11-17T03:27:11.507Z",
                "location": "[DOWNLOAD_URL]",
                "name": "d4c52078-0935-4255-aafd-c889726b5a9c/manifest.json"
            }
        ]
    },
    "created_on": "2022-11-16T03:19:45.458Z",
    "error_hints": [],
    "id": "d4c52078-0935-4255-aafd-c889726b5a9c",
    "last_message": "Manifest delivery completed",
    "last_modified": "2022-11-16T03:21:57.218Z",
    "name": "fallback order",
    "order_type": "partial",
    "products": [
        {
            "item_ids": [
                "20220304_093300_37_2430",
                "20220304_093257_90_2430"
            ],
            "item_type": "PSScene",
            "product_bundle": "analytic_8b_udm2"
        },
        {
            "item_ids": [
                "20220304_103324_1105",
                "20220304_103325_1105"
            ],
            "item_type": "PSScene",
            "product_bundle": "analytic_udm2"
        }
    ],
    "source_type": "scenes",
    "state": "success"
}

Download an Order

You can download the output of an order simply by following the location URL in the order's results.

Example Request

GET https://api.planet.com/compute/ops/download/?token=...

List Orders

You can get a list of all orders created within the last three months with the following request:

GET https://api.planet.com/compute/ops/orders/v2/

Query Parameters

The List Orders endpoint supports filtering on state with the following query parameters appended to the request:

  • ?state=<queued|running|success|partial|failed|cancelled>

Orders created more than three months ago will not be available through the Orders API. You can submit a request for inquiries about orders placed more than three months ago.

Example Request

GET https://api.planet.com/compute/ops/orders/v2/?state=queued

Example Response

The List Orders response will return a paged list of all your queued orders placed in the last three months with an order schema that is consistent with the Get Order response.

Cancel an Order

Orders may be cancelled while they are in a queued state. After an order moves into a running state, it may no longer be cancelled.

You can cancel a single order with the following request:

PUT https://api.planet.com/compute/ops/orders/v2/{order_id}

Example Request*

PUT https://api.planet.com/compute/ops/orders/v2/adfaaa2b-947b-4ca8-9faf-44340db6dcfa

Bulk Cancel Orders

The Orders API supports two bulk order cancel methods:

  1. Bulk cancel all queued orders
  2. Bulk cancel a specified list of order_ids

Bulk Cancel queued Orders

You can cancel all of your "queued" orders by POST-ing an empty JSON object ({}) to https://api.planet.com/compute/ops/bulk/orders/v2/cancel

Example Request*

POST https://api.planet.com/compute/ops/bulk/orders/v2/cancel

{}

Example Response* The response will include a count of orders which were successfully concelled, or which failed to cancel.

{
  "result": {
    "failed": {
      "count": 0,
      "failures": []
    },
    "succeeded": {
      "count": 6
    }
  }
}

Note

Because of the asynchronous nature of the Planet's 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, we cannot guarantee that all 100% of orders "queued" at the time of the request will be successfully cancelled.

Bulk Cancel Specified Orders

You can cancel a set of orders orders by POST-ing an array of order_ids to https://api.planet.com/compute/ops/bulk/orders/v2/cancel

Example Request

POST https://api.planet.com/compute/ops/bulk/orders/v2/cancel

{
   "order_ids": [
      "6031093e-90b7-4a94-9eb6-f3e5ca976a78",
      "dd2e95fa-a4bb-447f-93a1-44fe0ba80d3d",
      "04cf3dff-1774-4b2b-888d-a090de15023e",
      "08989bf2-8d9c-44d7-8b7d-f23d89ae2be9",
      "afe85e41-170f-40eb-8c98-c511e0814604",
      "34de3a40-ae7a-4904-abea-3aaf64f79e99"
   ]
}

Example Response

{
  "result": {
    "failed": {
      "count": 2,
      "failures": [
        {
          "message": "Order not in a cancellable state",
          "order_id": "afe85e41-170f-40eb-8c98-c511e0814604"
        },
        {
          "message": "Order not in a cancellable state",
          "order_id": "34de3a40-ae7a-4904-abea-3aaf64f79e99"
        }
      ]
    },
    "succeeded": {
      "count": 4
    }
  }
}

In the response above, two of the six orders failed to successfully cancel.

Aggregate Orders Stats

You can view the status of your organization's running and queued orders with the following request:

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 Request

GET https://api.planet.com/compute/ops/stats/orders/v2

Example Response

{
    "organization": {
        "queued_orders": 5,
        "running_orders": 352
    },
    "user": {
        "queued_orders": 0,
        "running_orders": 1
    }
}
Rate this guide: