Basic Ordering

Basic Ordering

A basic imagery order includes a set of item ids, an item type, and a product bundle – a predefined set of imagery and metadata assets.

  • item_ids: represent the catalog items 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.
  • item_type: represents the class of spacecraft and processing characteristics of a catalog item. Examples item types include PSScene4Band and SkySatCollect. You can read more about item types on our Imagery Reference page.
  • product_bundles: are an Orders API-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 will only be delivered for an order if all the assets in its specified product bundle are available. You can read more about imagery 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",
   "products":[
      {  
         "item_ids":[  
            "20200922_183724_23_106a",
            "20200922_183722_17_106a",
            "20200922_183720_11_106a"
         ],
         "item_type":"PSScene4Band",
         "product_bundle":"analytic"
      }
   ]
}

Example Response

{
    "created_on": "2020-09-24T22:44:52.572Z",
    "id": "49aea3d9-79a5-4743-af53-64935e72cd9b",
    "last_message": "Preparing order",
    "last_modified": "2020-09-24T22:44:52.572Z",
    "name": "simple_order",
    "products": [
        {
            "item_ids": [
                "20200922_183724_23_106a",
                "20200922_183722_17_106a",
                "20200922_183720_11_106a"
            ],
            "item_type": "PSScene4Band",
            "product_bundle": "analytic"
        }
    ],
    "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 any single bundle fails to deliver, or 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_sr product bundle example provided above, a partial order would deliver all the items in the order which have all analytic_sr, analytic_xml, and udm 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",
   "order_type":"partial",
   "products":[
      {  
         "item_ids":[  
            "20200922_183724_23_106a",
            "20200922_183722_17_106a",
            "20200922_183720_11_106a"
         ],
         "item_type":"PSScene4Band",
         "product_bundle":"analytic"
      }
   ]
}

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 bundle for an item, if all the assets in the analytic_sr 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":"simple_order_with_fallback",
   "products":[
      {  
         "item_ids":[  
            "20200922_183724_23_106a",
            "20200922_183722_17_106a",
            "20200922_183720_11_106a"
         ],
         "item_type":"PSScene4Band",
         "product_bundle":"analytic_sr,analytic"
      }
   ]
}

Order States

Order state represents the state of the order in its lifecycle.

Queued

The order is accepted and in the queue to run. All orders will start in a “queued” state before they start “running”. Within an organization, orders in the “queued” state will be moved into “running” in round-robin order by API key across all of the organization’s active orders to ensure that no single org user can impact order delivery times for other users in their org. Each organization can keep up to 10,000 orders total in their queue.

The time an order spends in a “queued” state will depend on:

  1. The number of orders an organization has submitted in a concise time period, resulting in a deeper order queue.
  2. The size of orders (items per order) ahead of the order in the queue, contributing to longer run times and queue durations.
  3. The number of orders queued across the entire ordering system.

In general, Planet targets a “queued” time of less than 2 minutes for customers with standard ordering patterns.

Running

The order is currently being processed.

The time an order stays in “running” will depend on:

  1. The item_types included in the order. Item types which are known to coincide with long order running times include PSOrthoTile, REOrthoTile, and SkySatCollect due to the longer activation times.
  2. The size of the order (items per order). While orders with more items will take longer to run, the Orders API was designed to service a bulk ordering use case. As such, orders with more items will have a shorter per-item running times. Wherever possible, Planet recommends ordering fewer orders with more items per order, to keep per-item running times low.
  3. The raster processing tools included in the order (you can learn more about tools in the Tools & Toolchains page.

Success

The order is complete and was successful; bundles were delivered for all items.

Partial

The order is complete and was partially successful; bundles were delivered for some items. As described in the earlier section on the partial order type, this state will only be valid for orders where order_type = partial.

Generally, orders with a state of partial indicate that bundles for certain items were not delivered because certain assets required in those bundles were not available for those items, the requester lacked permission to download certain assets, or certain bundles failed to deliver for unknown reasons.

Failed

The order failed. Orders may fail due to permission issues, lack of availability of certain asset types (especially if the order_type is full), other validation issues, or internal errors. Details on order failure will be supplied in the error_hints field.

Cancelled

The order was cancelled and will not be completed.

Ordering Multiple Item Types

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

Example Request

POST https://api.planet.com/compute/ops/orders/v2
{  
   "name":"multiple_item_type_order",
   "products":[
      {  
         "item_ids":[  
            "20200922_183724_23_106a",
            "20200922_183722_17_106a",
            "20200922_183720_11_106a"
         ],
         "item_type":"PSScene4Band",
         "product_bundle":"analytic"
      },
      {
        "item_ids": [
            "20171226_222055_6021709_RapidEye-3"
        ],
        "item_type": "REOrthoTile",
        "product_bundle": "analytic"
  }
   ]
}

Tips for Ordering Multiple Item Types: * It is not recommended to order both PlanetScope (or RapidEye) and Skysat item_types in the same order. The reason is that the Orders API may only decrement quota from a single Admin subscription. Because quota for PlanetScope/RapidEye and SkySat are typically hosted in two separate Admin subscriptions, orders including both item types are likely to fail. Instead, it is recommended that you order PlanetScope and SkySat items in distinct orders. Please reach out to support@planet.com 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/49aea3d9-79a5-4743-af53-64935e72cd9b 

Example Response

{
  "_links": {
    "_self": "https://api.planet.com/compute/ops/orders/v2/66139753-60e4-4926-a8ad-c556048aabce",
    "results": [{
      {
        "delivery": "success",
        "name": "PSScene4Band/20151119_025740_0c74/analytic",
        "expires_at": "0001-01-01T00:00:00.000Z",
        "location": "DOWNLOAD_URL"
      },
      {
        "delivery": "success",
        "name": "PSScene4Band/20151119_025740_0c74/analytic_xml",
        "expires_at": "0001-01-01T00:00:00.000Z",
        "location": "DOWNLOAD_URL"
      },
      {
        "delivery": "success",
        "name": "PSScene4Band/20151119_025740_0c74/udm",
        "expires_at": "0001-01-01T00:00:00.000Z",
        "location": "DOWNLOAD_URL"
      }
    ]
  },
  "created_on": "2018-01-09T19:11:51.563Z",
  "id": "66139753-60e4-4926-a8ad-c556048aabce",
  "last_message": "Delivery completed",
  "last_modified": "2018-01-09T21:41:09.170Z",
  "name": "simple order",
  "error_hints": [ ],
  "products": [{
    "item_ids": [
      "20151119_025740_0c74"
    ],
    "item_type": "PSScene4Band",
    "product_bundle": "analytic"
  }],
  "state": "success"
}
{
    "_links": {
        "_self": "https://api.planet.com/compute/ops/orders/v2/49aea3d9-79a5-4743-af53-64935e72cd9b",
        "results": [
            {
                "delivery": "success",
                "expires_at": "2020-09-25T23:29:05.037Z",
                "location": "https://api.planet.com/compute/ops/download/?token=..."
                "name": "49aea3d9-79a5-4743-af53-64935e72cd9b/PSScene4Band/20200922_183720_11_106a_3B_AnalyticMS_metadata.xml"
            },
            {
                "delivery": "success",
                "expires_at": "2020-09-25T23:29:05.040Z",
                "location": "https://api.planet.com/compute/ops/download/?token=..."
                "name": "49aea3d9-79a5-4743-af53-64935e72cd9b/PSScene4Band/20200922_183720_11_106a_3B_AnalyticMS_DN_udm.tif"
            },
            {
                "delivery": "success",
                "expires_at": "2020-09-25T23:29:05.043Z",
                "location": "https://api.planet.com/compute/ops/download/?token=..."
                "name": "49aea3d9-79a5-4743-af53-64935e72cd9b/PSScene4Band/20200922_183720_11_106a_3B_AnalyticMS.tif"
            },
            {
                "delivery": "success",
                "expires_at": "2020-09-25T23:29:05.046Z",
                "location": "https://api.planet.com/compute/ops/download/?token=..."
                "name": "49aea3d9-79a5-4743-af53-64935e72cd9b/PSScene4Band/20200922_183720_11_106a_metadata.json"
            },
            {
                "delivery": "success",
                "expires_at": "2020-09-25T23:29:05.050Z",
                "location": "https://api.planet.com/compute/ops/download/?token=..."
                "name": "49aea3d9-79a5-4743-af53-64935e72cd9b/PSScene4Band/20200922_183722_17_106a_3B_AnalyticMS_metadata.xml"
            },
            {
                "delivery": "success",
                "expires_at": "2020-09-25T23:29:05.053Z",
                "location": "https://api.planet.com/compute/ops/download/?token=..."
                "name": "49aea3d9-79a5-4743-af53-64935e72cd9b/PSScene4Band/20200922_183722_17_106a_3B_AnalyticMS_DN_udm.tif"
            },
            ...
        ]
    },
    "created_on": "2020-09-24T22:44:52.572Z",
    "error_hints": [],
    "id": "49aea3d9-79a5-4743-af53-64935e72cd9b",
    "last_message": "Manifest delivery completed",
    "last_modified": "2020-09-24T22:46:56.974Z",
    "name": "simple_order",
    "products": [
        {
            "item_ids": [
                "20200922_183724_23_106a",
                "20200922_183722_17_106a",
                "20200922_183720_11_106a"
            ],
            "item_type": "PSScene4Band",
            "product_bundle": "analytic"
        }
    ],
    "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 order_state with the following query parameters appended to the request: * ?order_state=

Orders created more than three months ago will not be available through the Orders API. You can reach out to support@planet.com for inquiries about orders placed more than three months ago.

Example Request

GET https://api.planet.com/compute/ops/orders/v2/?order_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/f12bc37d-ffce-423e-9a9a-deb34a423b82

Example Reponse

{
  "_links": {
    "_self": "https://api.planet.com/compute/ops/orders/v2/f12bc37d-ffce-423e-9a9a-deb34a423b82"
  },
  "created_on": "2019-11-15T16:13:53.232Z",
  "error_hints": [],
  "id": "f12bc37d-ffce-423e-9a9a-deb34a423b82",
  "last_message": "Cancel success",
  "last_modified": "2019-11-15T16:16:00.512Z",
  "name": "test-single-cancel",
  "products": [
    {
      "item_ids": [
        "20160603_130605_0c66"
      ],
      "item_type": "PSScene3Band",
      "product_bundle": "visual"
    },
    {
      "item_ids": [
        "20191026_171453_0f17",
        "20191025_171719_0f25"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "state": "cancelled"
}

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