Skip to main content

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

After a Tasking Order has been entered, you may check the Tasking API for the status of that Tasking Order. The diagram below outlines how Tasking Orders flow through the system.

Tasking rder status.

Tasking rder status.

  • Received: The Tasking Order has been entered into the system.
  • Rejected: The Tasking Order could not be accepted due to it not passed feasibility checks, for example, tessellation if it is an area order
  • Pending: The Tasking Order has been accepted but has not yet reached its start time
  • In progress: The Tasking Order’s start time has passed, and it is ready to be scheduled. Time in this state will depend on local cloud cover and collection capacity. Tasking Orders that have taken captures which did not meet specifications will stay in IN_PROGRESS while they are re-tasked.
  • Fulfilled: The Tasking Order has a capture which meets fulfillment specifications.
  • Cancelled: The Tasking Order was cancelled. Orders may be cancelled if they are Pending or IN_PROGRESS, however captures already Queued, Processing or Published at the time of cancellation, may still be subject to charge (see Capture Status for details).
  • Expired: The order’s end time has passed, all of its captures have been Published, and none meet specifications. The order will no longer be scheduled for imaging.

Tasking Order Status Example

To see the status of your order, you can make GET request for your order id. You can also filter orders by additional order metadata. See our 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 takes 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 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 thusly:

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

This means that the above RRule will create an order that will capture 1 image per week for 4 weeks, with the start time of the first capture being the date/time defined in the start_time parameter.

But what happens if you create your Monitoring Tasking Order on a Wednesday and you want the cadence to run from Monday to Sunday but you still want to use the rest of the week you are in to take the first capture. This can be achieved using a combination of the BYDAY RRule parameter and the early_start flag in the order payload.

RRule restrictions​

Some restrictions do apply to how the RRule format can be used to set up Monitoring Tasking Orders. The following should be taken into account when creating you order:

  • The maximum number of monitoring instances for a single Monitoring Tasking Order is 365
  • The minimum length of a single monitioring instance is 1 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

Taking all of this into consideration, let's see what is involved in creating such a Monitoring Order:

Creating a Monitoring Order​

Creation of monitoring orders is similar to the flexible tasking operations, extended with the 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
}'

Note the lack of a start_time in this request. If the start_time is omitted then the system will take 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 5 captures, the time of interest of the first capture spanning from the time that the order was created to the end of that week, with the next capture time of interest starting on the following Monday, which is 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.

If you want to know how your Monitoring Order is doing, you can set up email notifications so you can be automatically informed when a new capture is taken (see Notification and History)

Checking the status of your monitoring order​

If you want to check the status of a monitoring order programmatically, the first thing is to make a 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 contains presenting 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 the captures themselves, the following call can be made to the tasking/v2/captures endpoint, which will return all 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