The Planet Tasking API is a REST based 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.
The creation of an Assured Tasking Order follows the same rules as normal orders, but with a couple of extra steps along the way.
Request Imaging Windows¶
Assured Tasking allows the creation of a Tasking Order that is "assured" to take place at a given time and date of a satellite passing over the provided geo-coordinate. To do this, we first query the Tasking API to retrieve the available imaging windows that will satisfy the provided geo-coordinates and timeframe. This is done by calling the tasking/v2/imaging-windows/ endpoint of the Tasking API:
curl --request POST \
--url https://api.planet.com/tasking/v2/imaging-windows/ \
--header 'authorization: api-key <YOUR_API_KEY>' \
--header 'content-type: application/json' \
--data '{
"start_time": "2020-07-24T00:52Z",
"end_time": "2020-07-26T00:52Z",
"geometry": {
"coordinates": [
61.874999999998835,
48.69096039092497
],
"type": "Point"
},
"pl_number": "<PL-YourPlanetNumber>",
"product": "Assured Tasking",
"satellite_elevation_angle_min": 60,
"satellite_elevation_angle_max": 90
}'
The required fields for requesting the available imaging windows are:
geometry: a GeoJSON objectpl_number: your Planet Number, which begins with PLproduct: here, the product isAssured Tasking
The request also includes the optional satellite_elevation_angle_min and satellite_elevation_angle_max fields, in this case set to 60° and 90°, respectively. These angles define the desired orientation of the satellite when it takes the image. Note that the more restrictive the angle, the lower the likelihood that the Tasking Order succeeds.
The response body is empty, instead we have to look into the response headers for the location field, which contains a url path with a search_id that we then use in a GET request to the same endpoint:
curl --request GET \
--url 'https://api.planet.com/tasking/v2/imaging-windows/?search_id=<SEARCH_ID>' \
--header 'authorization: api-key <YOUR_API_KEY>' \
--header 'content-type: application/json'
This request returns an array of available imaging windows:
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "b964e2a8-0a8b-4a83-a05d-8ac025c0f799",
"assured_tasking_tier": "STANDARD",
"geometry": {
"geojson": {
"type": "Point",
"coordinates": [
61.874999999998835,
48.69096039092497
]
},
"geometry": {
"type": "Point",
"coordinates": [
61.875,
48.69096
]
}
},
"start_time": "2020-07-24T06:48:56.333000Z",
"end_time": "2020-07-24T06:50:03.528000Z",
"conflicting_orders": [],
"quota_priority_multiplier": 1.0,
"start_off_nadir": 31.22424,
"end_off_nadir": 31.23145,
"created_time": "2020-07-23T15:41:06.820966Z"
},
{
"id": "6891485e-3c9a-475b-8504-081d086b5fcd",
"assured_tasking_tier": "STANDARD",
"geometry": {
"geojson": {
"type": "Point",
"coordinates": [
61.874999999998835,
48.69096039092497
]
},
"geometry": {
"type": "Point",
"coordinates": [
61.875,
48.69096
]
}
},
"start_time": "2020-07-24T06:27:33.841000Z",
"end_time": "2020-07-24T06:28:41.827000Z",
"conflicting_orders": [],
"quota_priority_multiplier": 1.0,
"start_off_nadir": 31.22825,
"end_off_nadir": 31.22892,
"created_time": "2020-05-23T15:41:06.828251Z"
}
]
}
Creating an Assured Tasking Order¶
Each of these windows represents a time period that a satellite will be passing over the provided geo-coordinates. Taking one of these windows, we can then create an Assured Tasking Order that includes the id of the selected window.
NOTE
The geo-coordinates provided to the tasking/v2/imaging-windows/ request MUST also be used in the creation of the Order, otherwise the order is rejected. No start_time or end_time should be provided, as these are taken from the selected imaging 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',
'geometry': {
'type': 'Point',
'coordinates': [
61.874999999998835,
48.69096039092497
]
},
'imaging_window': '6891485e-3c9a-475b-8504-081d086b5fcd'
}
Automated Replacement of Existing Assured Orders via the API¶
Order replacement occurs when a new order reuses an imaging opportunity from an existing order that becomes available by the existing order. This removes the necessity of manually canceling existing orders in the hopes 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.
Request Imaging Windows with Conflicting Orders¶
In case we would like to include imaging windows with conflicting orders in the response, we have to provide a new GET parameter show_replacing_imaging_windows set to true. Only in this case the tasking API will indicate the ability to replace an existing order on each returned imaging window. All imaging windows will contain two new fields to inform the user about the replacement process: conflicting_orders and quota_priority_multiplier:
curl --request GET \
--url 'https://api.planet.com/tasking/v2/imaging-windows/?search_id=<SEARCH_ID>&show_replacing_imaging_windows=true' \
--header 'authorization: api-key <YOUR_API_KEY>' \
--header 'content-type: application/json'
This request returns an array of available imaging windows and will contain imaging windows with conflicting orders if any:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "c0fedd4a-4e04-4dbc-9c19-812ddb108c7e",
"assured_tasking_tier": "STANDARD",
"geometry": {
"geojson": {
"type": "Point",
"coordinates": [
61.874999999998835,
48.69096039092497
]
},
"geometry": {
"type": "Point",
"coordinates": [
61.875,
48.69096
]
}
},
"start_time": "2020-07-24T06:48:56.333000Z",
"end_time": "2020-07-24T06:50:03.528000Z",
"conflicting_orders": [
{
"id": "886ed050-a16b-4c5d-a252-c805720afd80",
"name": "Existing order",
}
],
"quota_priority_multiplier": 1.0,
"start_off_nadir": 31.22424,
"end_off_nadir": 31.23145,
"created_time": "2020-07-23T15:41:06.820966Z"
}
]
}
conflicting_orders¶
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. It is also possible that an imaging window requires the cancellation of multiple orders to be usable. The conflicting_orders will always list all of them. Imaging windows that are available without the need to replace an order, this list will simply be empty. quota_priority_multiplier The quota_priority_multiplier indicates the quota cost associated with this imaging window. If the replacement happens <24h before collection time and cancels 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.
Order Submission¶
As stated above, the order submission process does not change in the context of this feature. Simply passing the ID of an imaging window in the order submission will make use of the replacement. Once the imaging window of the new order has been confirmed and locked in, you will see the conflicting orders getting canceled automatically.
Should you want to avoid the cancellation of conflicting orders altogether, upon searching for imaging windows, you may simply preclude any imaging windows with one or more items in the conflicting_orders list. Imaging windows with no conflicting_orders will not cause any cancellations of existing orders.