Bulk POST and GET examples

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 Create

POSTing to the bulk create endpoint allows multiple orders of up to 1000 orders in total in a single, asynchronous request. The initial POST returns a BulkSummary response, which contains an ID that can be then be used to query the current status of the Bulk creation in the system.

The id passed as shown in the below (in this case "example_uuid_string") request must be a generated UUID string. This is an optional field. If no UUID is provided, one will be generated and returned in 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]
        }}]
}'

The is no body included in a response when the request is successful, only 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 making the request for 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:

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 be a 200 response with a JSON body, looking 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": 2,
  "status": "COMPLETE",
  "processing_payload_count": 0,
  "failed_payload_count": 0,
  "successful_payload_count": 2
}

In this example the two orders (or payloads) where successful, so no need to go further. However, if there are any payloads that are still in processing or actually failed, then a more detailed response can be requested, using the same URL as the previous GET request, but with /payloads appended to the end:

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": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "921be80b-b351-4e2b-afba-3384aa0b63e9",
      "bulk_process": "BulkProcess object (d722f658-cf66-4d00-8d3c-e286d5ca77ee)",
      "order_id": null,
      "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": null,
      "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"
      }
    }
  ]
}

Bulk Edit

The Bulk edit endpoint allows the editing of multiple orders in a single request, negating the need to make multiple requests for multiple orders. The request for bulk editing 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 field that defaults to CREATE (which is why we did not includ it in the bulk create example) but can also be set to EDIT and DELETE (the delete example is below).

Things to be aware of - This will only work for Orders that are in the system. Because of this, each Order to be edited must be identified with its ID. - Fields that are not present in the order payloads are left alone - A UUID for the bulk process is optional - The process is, like CREATE, 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',
            'geometry': {
                "type": "Point",
                "coordinates": [32.142035, -0.487188]
            }
        },
        {
            'id': 'order_UUID_2',
            'geometry': 
            {
                "type": "Point",
                "coordinates": [52.142035, 13.487188]
            }
        }],
    'operation_type': 'EDIT'
}'

The rest of the workflow is the same as with bulk creation, which can be followewd above.

Bulk cancel

Bulk cancellation allows multiple orders that exist in the system to be cancelled with a single POST request, with the following caveat: only orders with the status PENDING and IN PROGRESS may be cancelled

Things to be aware of - This will only work for Orders that are in the system. Because of this, each Order to be edited must be identified with its ID. - The operation_type must be set as DELETE - A UUID for the bulk process is optional - The process is, like CREATE, 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': 'DELETE'
}'