Assured Tasking

Assured Tasking orders are one option of the tasking orders that can be created using 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 Area of Interest (AOI). This specific imaging opportunity is the 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, query the Tasking API to retrieve the available imaging windows that will satisfy the provided AOI and TOI. Create an asynchronous search request using the imaging window search endpoint:

CURL

curl --request POST \
--url 'https://api.planet.com/tasking/v2/imaging-windows/search/' \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "geometry": {
      "coordinates": [
        13.350097,
        52.514511
      ],
      "type": "Point"
    },
    "pl_number": "$PL_CONTRACT_NUMBER",
    "product": "Assured Tasking"
}'

The required fields to place an imaging windows search request include the following:

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 can include optional constraints, including:

start_time and end_timeto configure the timeframe to search for imaging windows (For example, it cannot be more than seven days in the future)
sat_elevation_angle_min and sat_elevation_angle_max, to limit the desired elevation angle of the satellite when acquiring the imagery. 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 following search request:

{
  "id": "b7a4a198-17ea-45e2-baa1-766aaae3fab7",
  "imaging_windows": [],
  "status": "CREATED",
  "pl_number": "$PL_CONTRACT_NUMBER",
  "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
}

The status of the search request is CREATED and the array of results in imaging_windows is still empty. After submitting the search request, it is executed in the background asynchronously, and results will become available gradually 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

curl --request GET \
--url 'https://api.planet.com/tasking/v2/imaging-windows/search/b7a4a198-17ea-45e2-baa1-766aaae3fab7/' \
--header "Authorization: api-key $PL_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": "$PL_CONTRACT_NUMBER",
  "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
}

The resulting imaging_windows are populated and the status of the search request as DONE. This indicates that all matching imaging windows are added to the imaging_windows array, and no additional imaging windows will be returned.

!!! info "Retrieving Pricing Information" Detailed pricing information is retrieved by using the order_template__exclusivity_days query parameter along with the request. It specifies the number of days (0, 7, or 30). Captured imagery will be held exclusive to the organization that placed the order using the given imaging window. The response includes 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

Use one of the imaging windows to create an Assured Tasking order and include the id of the selected window.

CURL

curl --request POST 'https://api.planet.com/tasking/v2/orders/' \
--header 'Accept: application/json' \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "name": "Assured Tasking order 01",
  "imaging_window": "a3809a14-acf8-473a-b586-62ba76cfd451",
  "pl_number": "'"$PL_CONTRACT_NUMBER"'",
  "product": "Assured Tasking"
}'

Automated Replacement of Existing Assured Orders

Order replacement occurs when a new order reuses the imaging opportunity of an existing order. You will not need to manually cancel existing orders to free up capacity and place a new order with the same AOI and TOI. Planet replaces the order for you. 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 the successful scheduling of the new order will initiate the cancellation of the existing order.

To avoid accidental replacement, opt in to display 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

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 $PL_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. Conflicting orders are listed. The list is empty for the imaging windows that are available without the need to replace an order.

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

Searching For Imaging Windows​

Creating an Assured Tasking Order​

Automated Replacement of Existing Assured Orders​

Searching For Imaging Windows

Creating an Assured Tasking Order

Automated Replacement of Existing Assured Orders