Skip to main content

Flexible Tasking

Flexible tasking is a way to order high-resolution imagery where Planet chooses an optimal collection schedule. For high-quality collects, all collected images undergo quality assessment. If the assessment flags the image as below the requested standards, retasking occurs.

After your enter a Tasking Order, check the Tasking API for the status. The diagram displays how Tasking Orders are generated.

Tasking order status.

Tasking order status.

  • Received: The Tasking Order is entered into the system.
  • Rejected: The Tasking Order is not accepted because it failed feasibility checks. For example, tessellation if it is an area order
  • Pending: The Tasking Order is accepted but has not reached its start time
  • In progress: The Tasking Order start time passed, and it is ready to be scheduled. Time in this state depends on local cloud cover and collection capacity. Tasking Orders that have taken captures which did not meet specifications remain in IN_PROGRESS during re-tasking.
  • Fulfilled: The Tasking Order captures the fulfillment specifications.
  • Cancelled: The Tasking Order was cancelled. Orders may be cancelled if they are Pending or IN_PROGRESS. Captures that are Queued, Processing or Published at the time of cancellation, could be charged. (see Capture Status for details).
  • Expired: The order end time has passed, all of its captures have been Published, and did not meet specifications. The order will no longer be scheduled for imaging.

Tasking Order Status Example​

To see the status of your order, request a GET request for your order ID. You can also filter orders by additional order metadata. Refer to the API reference for more information.

Endpoint

https://api.planet.com/tasking/v2/orders/?status=FULFILLED

Response example

{
  "id": "bfc45520-8a72-4d23-bfd1-7b22f23ed133",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [-77.306467, 45.435827],
        [-77.229787, 45.435827],
        [-77.22975, 45.489812],
        [-77.306504, 45.489812],
        [-77.306467, 45.435827]
      ]
    ]
  },
  "capture_status_published_count": 0,
  "capture_assessment_success_count": 0,
  "capture_assessment_invalid_count": 0,
  "start_time": "2019-09-30T20:30:50.836516Z",
  "end_time": "2020-09-27T23:59:59.999000Z",
  "created_time": "2019-09-30T20:30:51.807703Z",
  "name": "cairo_egypt",
  "status": "FULFILLED"
}

Monitoring Tasking​

A Monitoring order is a flexible tasking order that includes images of a location over a period of time at a defined cadence. The time period, cadence, and other options are defined by the provided RRule which allows for flexibility and accuracy in the creation of a monitoring order. In first the example below the rrule is defined as "FREQ=WEEKLY;COUNT=4;INTERVAL=1" which can be broken down as follows:

  • FREQ=WEEKLY: Defines that the Monitoring Tasking Order frequency should be oriented around calendar weeks
  • COUNT=4: Defines that this order should run four times
  • INTERVAL=1: States that the cadence should be every week. If this were set to 2, for example, the cadence would be every two weeks and 3 would be every three weeks and so on.

The above RRule creates an order that captures one image per week for four weeks. The start time of the first capture is the date/time, defined in the start_time parameter.

For exmaple, if you create a Monitoring Tasking Order on a Wednesday, and you want the cadence to run from Monday to Sunday, but you want to use the rest of the week to take the first capture. Use a combination of the BYDAY RRule parameter and the early_start flag in the order payload.

RRule Restrictions​

The following restrictions apply to the RRule format usage to configure Monitoring Tasking Orders. Consider the following when creating the order:

  • The maximum number of monitoring instances for a single Monitoring Tasking Order is 365
  • The minimum length of a single monitoring instance is one day. RRule definitions that attempt to set a cadence < 24HR will be rejected
  • The RRule option BYYEARDAY will be rejected
  • The RRule option FREQ=YEARLY will be rejected
  • The interval and count must both be > 0

Creating a Monitoring Order​

Creation of monitoring orders is similar to the flexible tasking operations, extended with scheduling information.

curl --request POST \
--url https://api.planet.com/tasking/v2/orders/ \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"geometry": {
  "type": "Point",
  "coordinates": [
      149.44135,
      28.49240
  ]
},
"name": "Test Monitoring Order",
"scheduling_type": "MONITORING",
"rrule": "FREQ=WEEKLY;COUNT=4;INTERVAL=1;BYDAY=MO",
"early_start": true
}'

If the start_time is omitted, the system uses the current time and date as the start time. The above request would, if created on any other day than a Monday:

  • attempt to collect five captures
  • the time of interest of the first capture, spanning from the time that the order was created to the end of that week
  • the next capture time of interest starting on the following Monday, defined by the BYDAY RRule parameter. Also note the lack of an end_time in this request. A Monitoring order's end-time is computed from the rrule, so the system will ignore the values of the field end_time, if provided in the payload.

To view the status of your Monitoring Order, set up email notifications for automated notifications. (see Notification and History)

Checking the Status of Your Monitoring Order​

To check the status of a monitoring order programmatically, set the call to the tasking/v2/orders endpoint with the ID of the Monitoring Order that you want to check:

curl --request GET \
--url https://api.planet.com/tasking/v2/orders/$TASKING_ORDER_ID \
--header "Authorization: api-key $PL_API_KEY" \
--header 'Content-Type: application/json'

The response from this request presents an overview of the capture status of the order as well as the status of the Tasking Order itself:

{
  "id": "ORDER_ID",
  ...
  ...
  ...
  "status": "IN_PROGRESS",
  "capture_count": 1,
  "capture_status_queued_count": 0,
  "capture_status_processing_count": 0,
  "capture_status_published_count": 1,
  "rrule": "FREQ=WEEKLY;COUNT=4;INTERVAL=1;BYDAY=MO",
  ...
  ...
  ...
}

To view captures, enter the following call: tasking/v2/captures. This returns all of the captures for the given Tasking Order ID:

curl --request GET \
--url 'https://api.planet.com/tasking/v2/captures/?order_id=$TASKING_ORDER_ID' \
--header 'Authorization: api-key  $PL_API_KEY' \
--header 'Content-Type: application/json'
Last updated on