Setting up Monitoring Orders

The Planet Tasking API is a REST based API, which can be integrated into any service, regardless of the language used. Below are some examples of how to create and maintain Monitoring orders.

The RRule¶

A Monitoring order is a 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¶

If you are already familiar with creating a standard Tasking Order, then setting a Monitoring Order isn't much different, it just needs a couple of extra fields to be defined. (If you are not familiar with setting up a Tasking Order, you can take a look at Tasking Orders)

curl --request POST \
  --url https://api.planet.com/tasking/v2/orders/ \
  --header 'authorization: api-key <YOUR_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.

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/<ORDER_ID_GOES_HERE> \
  --header 'authorization: api-key <YOUR_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=<ORDER_ID_GOES_HERE>' \
  --header 'authorization: api-key  <YOUR_API_KEY>' \
  --header 'content-type: application/json'

---

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

Send Us Your Feedback