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",
"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",
"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'
}