Tasking Order creation, editing and deletion

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 Orders creation, editing and cancellation.

Tasking Order creation

The creation of a order via the Tasking API is done via a POST request to the Tasking API tasking/v2/orders endpoint. The creation of Tasking Order can be a simple as the following request example:

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': 'Order 01',
        'geometry': {
            'type': 'Point',
            'coordinates': [
                149.44135,
                28.49240
            ]
        }
    }

Defining the minimum and maximum Satellite elevation angles

As part of the Tasking Order creation, it is possibe to define the acceptable range of angles relative to the target that the satellite should attempt to take an image. There values are sat_elevation_angle_min and sat_elevation_angle_max, and whilst both have a theoretical range from 0° to 90° it is likely that these values will be defined in your contract as having a range between 60° and 90° inclusive. The angles are relative to the target, so 90° is directly above the target and it should be noted that the more restrictive the range between the min and max values the more likely it is that you Tasking Order will not succeed.

Selecting the PL-Number and Product

If the PL-Number and Product are not defined in the order POST request, then the Tasking API service will select the default values that are defined for the given api-key. In the majority of cases this will be sufficient and thus the PL-Number and Product do not need to be defined. If a different PL-Number and/or product are to be chosen, then these can simply be defined as part of the order payload:

   {
        "name": "Order 01",
        "geometry": {
            "type'": "Point",
            "coordinates": [
                149.44135,
                28.49240
            ]
        },
        "pl_number": "PL-YourPlNumber",
        "product": "one_timne_tasking"
   }

The response will contain the UUID that has been generated to identify the newly created Tasking Order, as well as any geometry created and other values related to the Tasking Order:

the following response is truncated and does not contain all of the fields that might be returned in an order creation response

    {
        "id": "9d79b9ba-efa3-4e6d-bc08-407b545875a1",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
            [
                [
                    149.415829,
                    28.469843
                ],
                [
                    149.466885,
                    28.469843
                ],
                [
                    149.466896,
                    28.514958
                ],
                [
                    149.415818,
                    28.514958
                ],
                [
                    149.415829,
                    28.469843
                ]
            ]
            ]
        },
        "original_geometry": {
            "type": "Point",
            "coordinates": [
                149.441357,
                28.492403
            ]
        },
        "capture_count": 0,
        "order_type": "IMAGE",
        "priority": 1000,
        "start_time": "2020-03-23T12:26:35.820963Z",
        "end_time": "2020-04-22T12:26:35.820963Z",
        "cloud_threshold": 0.7,
        "created_time": "2020-03-23T12:26:36.137220Z",
        "updated_time": "2020-03-23T12:26:36.137259Z",
        "name": "test_order_426",
        "status": "PENDING",
        ...
        ...
        ...
    }

Tasking Order Editing

The ability to edit an existing Tasking Order depends what needs to be changed and the current status of the Tasking Order in the system. The following table shows what can be edited and in what state. Tasking Orders in the following states FULFILLED, CANCELLED and EXPIRED cannot be edited :

FIELD PENDING REQUESTED IN PROGRESS
name yes yes yes
start_time yes yes no
end_time yes yes yes

Rather than a POST request, an edit requires a PUT request to be made. The following command would edit the name and start time of a an existing Tasking Order. The UUID that identifies the order is including as part of the URL:

 curl --request PUT --url 'https://api.planet.com/tasking/v2/orders/<ORDER_ID_GOES_HERE>' \
    --header 'accept: application/json' \
    --header 'authorization: api-key <YOUR_API_KEY>' \
    --header 'content-type: application/json' \
    --data '{
        'start_time': '2020-04-23T12:26:35Z'
    }

With a response that shows the updated fields plus the other fields that can be edited:

    {
        "rank": 1,
        "start_time": "2020-05-23T12:26:35.000000Z",
        "end_time": "2020-06-23T12:26:35.000000Z"
    }

Tasking Order deletion

Tasking Order deletion follows similar rules to editing. Tasking Orders can be deleted or cancelled only when the Tasking Order is in one of the following states: PENDING, IN PROGRESS, RECEIVED and REQUESTED. A Tasking Order deletion is acheived by creating a DELETE request to the tasking/v2/orders endpoint with the ID of the Tasking Order that is to be deleted:

curl --request DELETE --url 'https://api.planet.com/tasking/v2/orders/<ORDER_ID_GOES_HERE>' \
    --header 'accept: application/json' \
    --header 'authorization: api-key <YOUR_API_KEY>' \
    --header 'content-type: application/json' \

Note the lack of a body in the request. A successful request receives a HTTP 204 response