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 integrate the most commonly used aspects of the Tasking API Bulk endpoint.
Bulk Statuses¶
Before going into the various aspects of Bulk creation, editing and cancellation, we will first look at the different statuses that can be attributed to a bulk operation. A bulk operation can have one of the following statuses:
PENDING : The bulk request has been received but work has yet to start on processing the payload. RUNNING : Work has starting on processing the payload. COMPLETE : The processing of the payload has finished.
Bulk Create¶
POSTing to the bulk endpoint allows up to 1000 Tasking Orders to be created in a single, asynchronous, request.
When putting together the bulk tasking order request you can optionally specify your own bulk tasking order ID beforehand, but it must be a UUID string otherwise it will be rejected. If no UUID is provided, one will be generated and returned as part of the response header location field (see below) This example also only creates point orders, but any order type can be created via a bulk request.
curl --request POST --url 'https://api.planet.com/tasking/v2/bulk/' \
--header 'accept: application/json' \
--header 'authorization: api-key <YOUR_API_KEY>' \
--header 'content-type: application/json' \
--data '{
"id": "example_uuid_string",
"order_payloads": [
{
"name": "Bulk order 1",
"geometry": {
"type": "Point",
"coordinates": [32.142035, -0.487188]
}
},
{
"name": "Bulk order 2",
"geometry": {
"type": "Point",
"coordinates": [52.142035, 13.487188]
}
},
{
"name": "Bulk order 3",
"geometry": {
"type": "Point",
"coordinates": [181, 40]
}
}
]
}'
There is no payload as part the response when the request is successful, and the response code is a 202, which denotes an asynchronous response. Included in the headers of the response is a location field which contains the URL that can be used for requesting the status of bulk order which is a GET request to the same endpoint, but this time appending the UUID that is used to identify the original bulk POST request to the URL:
curl --request GET --url 'https://api.planet.com/tasking/v2/bulk/example_uuid_string' \
--header 'accept: application/json' \
--header 'authorization: api-key <YOUR_API_KEY>' \
This time the response, when successful, will return with a response code of 200 and a JSON payload that will look similar to the following:
{
"id": "example_uuid_string",
"start_time": "2020-03-20T13:27:28.501032Z",
"end_time": "2020-03-20T13:27:30.317499Z",
"operation_type": "CREATE",
"payload_count": 3,
"status": "COMPLETE",
"processing_payload_count": 0,
"failed_payload_count": 1,
"successful_payload_count": 2
}
Note the operation_type is set to CREATE and that the status is COMPLETE.
In this example the two tasking orders that comprised the original bulk tasking order POST request were successfully ingested, so there is no need to go further. However, if there are any tasking orders that are still in processing or maybe even failed for some reason then a more detailed response can be requested, using the same URL as the previous GET request but with /payloads appended to the URL:
curl --request GET --url 'https://api.planet.com/tasking/v2/bulk/example_uuid_string/payloads' \
--header 'accept: application/json' \
--header 'authorization: api-key <YOUR_API_KEY>'
This will return a list of all the payloads in the original bulk POST, with the extra provided detail:
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": "921be80b-b351-4e2b-afba-3384aa0b63e9",
"bulk_process": "BulkProcess object (d722f658-cf66-4d00-8d3c-e286d5ca77ee)",
"order_id": "493d3e9e-176d-4617-b932-d7961f60949e",
"payload": {
"name": "Bulk order 1",
"altitude": 0,
"end_time": "2020-05-30T23:00:00Z",
"geometry": {
"type": "Point",
"coordinates": [
32.142035,
-0.487188
]
},
"start_time": "2020-04-28T00:00:00Z"
}
},
{
"id": "a1b4fd59-1b80-4fff-b670-659a64c0ba1e",
"bulk_process": "BulkProcess object (d722f658-cf66-4d00-8d3c-e286d5ca77ee)",
"order_id": "178631b4-f23e-46e6-a77b-789cc164fdbe",
"payload": {
"name": "Bulk order 2",
"altitude": 0,
"end_time": "2020-05-30T23:00:00Z",
"geometry": {
"type": "Point",
"coordinates": [
32.142032,
-0.487199
]
},
"start_time": "2020-04-28T00:00:00Z"
}
},
{
"id": "6fdf32db-a385-4034-8e13-c6b312ce297f",
"bulk_process": "BulkProcess object (d722f658-cf66-4d00-8d3c-e286d5ca77ee)",
"payload": {
"name": "Bulk order 3",
"altitude": 0,
"end_time": "2020-05-30T23:00:00Z",
"geometry": {
"type": "Point",
"coordinates": [
181,
40
]
},
"start_time": "2020-04-28T00:00:00Z"
},
"error": "{\"geometry\":[\"Geometry longitude coordinate needs to be within -180.0 and 180.0\"]}"
}
]
}
Bulk Edit¶
The Bulk edit endpoint allows the editing of multiple Tasking Orders in a single request, negating the need to make multiple requests for multiple Tasking Orders. The request for bulk editing Tasking Orders is very much the same as the one for bulk creation, but with the inclusion of the operation_type field, which is an optional parameter that defaults to CREATE (which is why we didn't include it in the bulk create example) but can also be set to EDIT and CANCEL (the cancel example is further down).
Things to be aware of
- This will only work for Tasking Orders that are in the system. Because of this each, Tasking Order to be edited must be identified by its ID.
- Fields that are not present in the order payloads are left alone.
- The operation_type must be set as EDIT
- A UUID for the bulk process is optional.
- The process is asynchronous.
- The editing of Tasking Orders via bulk follow the same rules as defined here
A curl request would look similar to this:
curl --request POST --url 'https://api.planet.com/tasking/v2/bulk/' \
--header 'accept: application/json' \
--header 'authorization: api-key <YOUR_API_KEY>' \
--header 'content-type: application/json' \
--data '{
'order_payloads': [
{
'id': 'order_UUID',
'start_time': '2021-04-29T00:00:00Z'
},
{
'id': 'order_UUID_2',
'end_time': '2021-05-29T00:00:00Z'
}],
'operation_type': 'EDIT'
}'
As with the Bulk creation workflow, there is no payload as part the response when the request is successful, and the response code is a 202, which denotes an asynchronous response. Included in the headers of the response is a location field which contains the URL that can be used for requesting the status of bulk edit which is a GET request to the same endpoint, but this time appending the UUID that is used to identify the original bulk POST request to the URL:
curl --request GET --url 'https://api.planet.com/tasking/v2/bulk/example_uuid_string' \
--header 'accept: application/json' \
--header 'authorization: api-key <YOUR_API_KEY>' \
This time the response, when successful, will return with a response code of 200 and a JSON payload that will look similar to the following:
{
"id": "5d11a1ed-4179-45f8-a9b4-65bc40c4bf64",
"start_time": "2021-03-19T14:28:51.141569Z",
"end_time": null,
"operation_type": "EDIT",
"payload_count": 2,
"status": "RUNNING",
"processing_payload_count": 2,
"failed_payload_count": 0,
"successful_payload_count": 0
}
Note that the operation_type is EDIT, reflecting the type of the original bulk request.
Bulk Cancel¶
Bulk cancellation allows multiple Tasking Orders that exist in the system to be cancelled with a single POST request, with the following caveat: only Tasking Orders with the statuses PENDING and IN_PROGRESS may be cancelled
Things to be aware of
- This will only work for Tasking Orders that are in the system. Because of this each Tasking Order to be cancelled must be identified by its ID.
- The operation_type must be set as CANCEL
- A UUID for the bulk process is optional
- The process is asynchronous
A curl request would look similar to this:
curl --request POST --url 'https://api.planet.com/tasking/v2/bulk/' \
--header 'accept: application/json' \
--header 'authorization: api-key <YOUR_API_KEY>' \
--header 'content-type: application/json' \
--data '{
'order_payloads': [
{
'id': 'order_UUID'
},
{
'id': 'order_UUID_2'
}],
'operation_type': 'CANCEL'
}'
As with the Bulk creation workflow, there is no payload as part the response when the request is successful, and the response code is a 202, which denotes an asynchronous response. Included in the headers of the response is a location field which contains the URL that can be used for requesting the status of bulk edit which is a GET request to the same endpoint, but this time appending the UUID that is used to identify the original bulk POST request to the URL:
{
"id": "7ed1516b-e65b-4886-a82d-5237b5738dd3",
"start_time": "2021-03-19T15:18:22.131747Z",
"end_time": "2021-03-19T15:18:22.850360Z",
"operation_type": "CANCEL",
"payload_count": 2,
"status": "COMPLETE",
"processing_payload_count": 0,
"failed_payload_count": 0,
"successful_payload_count": 2
}
Note that the operation_type is CANCEL, reflecting the type of the original bulk request.
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.