Assured Tasking Order Creation

last updated: September 04, 2024

The Planet Tasking API is a REST-ful API which can be integrated into any service, regardless of the language used. Assured Tasking orders are one of the varieties of tasking orders that can be created via the Tasking API. Assured Tasking allows the creation of a tasking order that is "assured" to take place at a specific Time of Interest (TOI) of a satellite passing over the provided geo-coordinate of an Area of Interest (AOI). This specific imaging opportunity is the so-called imaging window. The creation of an Assured Tasking order follows the same rules as normal tasking orders but requires the user to select an imaging window and include it as part of the order submission.

Searching For Imaging Windows

To select an imaging window, we first query the Tasking API to retrieve the available imaging windows that will satisfy the provided AOI and TOI. This is done by creating an asynchronous search request using the /tasking/v2/imaging-windows/search/ endpoint:

curl --request POST \
  --url 'https://api.planet.com/tasking/v2/imaging-windows/search/' \
  --header 'authorization: api-key <YOUR_API_KEY>' \
  --header 'content-type: application/json' \
  --data '{
      "geometry": {
        "coordinates": [
          13.350097,
          52.514511
        ],
        "type": "Point"
      },
      "pl_number": "<YourPLNumber>",
      "product": "Assured Tasking"
  }'

The required fields for placing an imaging windows search request are:

  • geometry: a GeoJSON representation of a Point or a two-point LineString to serve as the AOI for the imaging window search
  • pl_number: your Planet contract number, which begins with PL-
  • product: the product, which is Assured Tasking here

The request may include optional constraints, such as start_time and end_time to narrow down the timeframe in which to search for imaging windows (cannot be more than 7 days in the future), as well as sat_elevation_angle_min and sat_elevation_angle_max, to limit the desired elevation angle of the satellite when acquiring the imagery. Note that the more restrictive the search constraints are set, the lower the likelihood that matching imaging windows can be found.

The response contains a structured representation of the search request similar to this one:

{
  "id": "b7a4a198-17ea-45e2-baa1-766aaae3fab7",
  "imaging_windows": [],
  "status": "CREATED",
  "pl_number": "<YourPLNumber>",
  "product": "Assured Tasking",
  "geometry": {
    "type": "Point",
    "coordinates": [
      133.406128,
      -25.837374
    ]
  },
  "start_time": "2024-07-24T09:26:41.228492Z",
  "end_time": "2024-07-31T09:26:41.228492Z",
  "created_time": "2024-07-24T09:26:41.249987Z",
  "sat_elevation_angle_min": 58,
  "sat_elevation_angle_max": 90,
  "off_nadir_angle_min": 0,
  "off_nadir_angle_max": 30,
  "error_code": null,
  "error_message": null
}

At this point the status of the search request is CREATED, and the array of results in imaging_windows is still empty. After sbumitting the search request, it is executed in the background asynchronously, and results will become available gradually over the course of up to 5 minutes. We can inspect the current status and results of a search request at any time using the /tasking/v2/imaging-windows/search/{id} endpoint together with the id returned in the response above:

curl --request GET \
  --url 'https://api.planet.com/tasking/v2/imaging-windows/search/b7a4a198-17ea-45e2-baa1-766aaae3fab7/' \
  --header 'authorization: api-key <YOUR_API_KEY>' \
  --header 'content-type: application/json'

Resulting in a similar response:

{
  "id": "b7a4a198-17ea-45e2-baa1-766aaae3fab7",
  "imaging_windows": [
    {
      "id": "ca2be13d-e70c-4e0b-9cfe-f7e1c0cf96f6",
      "start_time": "2024-07-25T00:25:04.851000Z",
      "end_time": "2024-07-25T00:26:17.179000Z",
      "off_nadir_angle_start": 28.91166,
      "off_nadir_angle_end": 29.49281,
      "off_nadir_angle_min": 10.72227,
      "off_nadir_angle_max": 29.49281,
      "sat_elevation_angle_min": 58,
      "sat_elevation_angle_max": 78.45259,
      "sat_azimuth_angle_start": 350.98343,
      "sat_azimuth_angle_end": 209.96627,
      "sun_elevation_angle_min": 28.97,
      "sun_elevation_angle_max": 29.17,
      "solar_zenith_angle_min": 60.83256,
      "solar_zenith_angle_max": 61.02764,
      "low_light": false,
      "ground_sample_distance": 0.9,
      "assured_tasking_tier": "STANDARD",
      "cloud_forecast": [
        {
          "prediction": 53.4,
          "updated_time": "2024-07-24T09:26:52.626768Z"
        }
      ],
      "conflicting_orders": [],
      "quota_priority_multiplier": 1
    },
    {
      "id": "a3809a14-acf8-473a-b586-62ba76cfd451",
      "start_time": "2024-07-29T00:10:15.532000Z",
      "end_time": "2024-07-29T00:10:27.303000Z",
      "off_nadir_angle_start": 29.50553,
      "off_nadir_angle_end": 29.5026,
      "off_nadir_angle_min": 29.22695,
      "off_nadir_angle_max": 29.50553,
      "sat_elevation_angle_min": 58,
      "sat_elevation_angle_max": 58.30617,
      "sat_azimuth_angle_start": 93.76091,
      "sat_azimuth_angle_end": 111.18617,
      "sun_elevation_angle_min": 27.15,
      "sun_elevation_angle_max": 27.19,
      "solar_zenith_angle_min": 62.81368,
      "solar_zenith_angle_max": 62.84731,
      "low_light": false,
      "ground_sample_distance": 1.1,
      "assured_tasking_tier": "STANDARD",
      "cloud_forecast": [
        {
          "prediction": 0.9,
          "updated_time": "2024-07-24T09:26:52.666272Z"
        }
      ],
      "conflicting_orders": [],
      "quota_priority_multiplier": 1
    }
  ],
  "status": "DONE",
  "pl_number": "<YourPLNumber>",
  "product": "Assured Tasking",
  "geometry": {
    "type": "Point",
    "coordinates": [
      133.406128,
      -25.837374
    ]
  },
  "start_time": "2024-07-24T09:26:41.228492Z",
  "end_time": "2024-07-31T09:26:41.228492Z",
  "created_time": "2024-07-24T09:26:41.249987Z",
  "sat_elevation_angle_min": 58,
  "sat_elevation_angle_max": 90,
  "off_nadir_angle_min": 0,
  "off_nadir_angle_max": 30,
  "error_code": null,
  "error_message": null
}

Note here that the resulting imaging_windows are now populated and the status of the search request has changed to DONE. This indicates that all matching imaging windows have been added to the imaging_windows array, and no additional imaging windows will be returned.

Retrieving Pricing Information

Detailed pricing information can be retrieved for the individual imaging windows by passing order_template__exclusivity_days query parameter along with the request. It specifies the number of days (0, 7, or 30) for which captured imagery will be held exclusive to the organization that placed the order using the given imaging window. The response will include a pricing_details field that provides information on how the price was calculated for the imaging window. Additional information can be found under Tasking Order Pricing.

Creating an Assured Tasking Order

Using one of the found imaging windows, an Assured Tasking order can be created by including the id of the selected window.

  curl --request POST --url 'https://api.planet.com/tasking/v2/orders/' \
    --header 'accept: application/json' \
    --header 'authorization: api-key <YOUR_API_KEY>' \
    --header 'content-type: application/json' \
    --data '{
        "name": "Assured Tasking order 01",
        "imaging_window": "a3809a14-acf8-473a-b586-62ba76cfd451",
        "pl_number": "<YourPLNumber>",
        "product": "Assured Tasking"
      }'

Automated Replacement of Existing Assured Orders

Order replacement occurs when a new order reuses the imaging opportunity of an existing order. This we can avoid manually cancelling existing orders in the hope of freeing up capacity to place a new order over the same approximate AOI and TOI. Planet will take care of replacing the orders for you, and will do so in an "all or nothing" manner: if the lock-in of the new order cannot be confirmed due to scheduling issues on the satellite, the existing order will remain in place. Only successful scheduling of the new order will initiate the cancellation of the existing order.

To guard against accidental replacement the user has to opt in to show imaging windows that would replace existing orders. When retrieving the search request results we have to provide the show_replacing_imaging_windows query parameter as true:

curl --request GET \
  --url 'https://api.planet.com/tasking/v2/imaging-windows/search/b7a4a198-17ea-45e2-baa1-766aaae3fab7/?show_replacing_imaging_windows=true' \
  --header 'authorization: api-key <YOUR_API_KEY>' \
  --header 'content-type: application/json'

The result is an array of available results that will contain both regular imaging windows and imaging windows with conflicting orders that need replacement:

{
  "id": "b7a4a198-17ea-45e2-baa1-766aaae3fab7",
  "imaging_windows": [
    {
      "id": "ca2be13d-e70c-4e0b-9cfe-f7e1c0cf96f6",
      "start_time": "2024-07-25T00:25:04.851000Z",
      "end_time": "2024-07-25T00:26:17.179000Z",
      "off_nadir_angle_start": 28.91166,
      "off_nadir_angle_end": 29.49281,
      "off_nadir_angle_min": 10.72227,
      "off_nadir_angle_max": 29.49281,
      "sat_elevation_angle_min": 58,
      "sat_elevation_angle_max": 78.45259,
      "sat_azimuth_angle_start": 350.98343,
      "sat_azimuth_angle_end": 209.96627,
      "sun_elevation_angle_min": 28.97,
      "sun_elevation_angle_max": 29.17,
      "solar_zenith_angle_min": 60.83256,
      "solar_zenith_angle_max": 61.02764,
      "low_light": false,
      "ground_sample_distance": 0.9,
      "assured_tasking_tier": "STANDARD",
      "cloud_forecast": [
        {
          "prediction": 53.4,
          "updated_time": "2024-07-24T09:26:52.626768Z"
        }
      ],
      "conflicting_orders": [
        {
          "id": "886ed050-a16b-4c5d-a252-c805720afd80",
          "name": "Existing Order to Replace",
          "off_nadir_angle_min": 11.1,
          "off_nadir_angle_max": 29.02,
          "sat_elevation_angle_min": 58,
          "sat_elevation_angle_max": 78,
          "assured_tasking_tier": "STANDARD",
          "cloud_forecast": [
            {
              "prediction": 54.0,
              "updated_time": "2024-07-24T09:21:12.851000Z"
            }
          ]
        }
      ],
      "quota_priority_multiplier": 1
    },
  ],
  ...
}

For each imaging window, the conflicting_orders field lists the existing orders that conflict with this imaging window, and will be replaced if the imaging window is used to submit a new order. An imaging window may require the cancellation of multiple orders to be usable. The conflicting orders will always list all of them. For imaging windows that are available without the need to replace an order this list will be empty.

Order Replacement Pricing

For each imaging window, the quota_priority_multiplier indicates the quota cost associated with this imaging window. If a replacing imaging window is less than 24 hours in the future, and involves the replacement of more than one existing order, the quota_priority_multiplier will sum up the priority multipliers of all the existing orders. For example, an imaging window that requires the replacement of two orders with the assured_tasking_tier=STANDARD, the multiplier would be 2.0 (1.0 + 1.0). For two EXPRESS orders, the multiplier would be 3.0 (1.5 + 1.5). If the priority multiplier of the new imaging window is higher, then it will be used. For example, if an imaging window with assured_tasking_tier=EXPRESS replaces an order with assured_tasking_tier=STANDARD, the multiplier will be 1.5.


We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.

Send Us Your Feedback