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.

Order creation

The creation of a order via the Tasking API is done via a POST request to the Tasking API /orders endpoint. The creation of an 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
        ]
    }
}

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 order, as well as any geometry created and other values related to the 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
            ]
        ]
        ]
    },
    "originalGeometry": {
        "type": "Point",
        "coordinates": [
            149.441357,
            28.492403
        ]
    },
    "captureCount": 0,
    "orderType": "IMAGE",
    "priority": 1000,
    "startTime": "2020-03-23T12:26:35.820963Z",
    "endTime": "2020-04-22T12:26:35.820963Z",
    "cloudThreshold": 0.7,
    "taskIds": [
        "fbeff373-c188-4fca-982c-592705e11c68"
    ],
    "createdTime": "2020-03-23T12:26:36.137220Z",
    "updatedTime": "2020-03-23T12:26:36.137259Z",
    "name": "test_order_426",
    "status": "PENDING",
    ...
    ...
    ...
}

Order Editing

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

FIELD PENDING REQUESTED IN PROGRESS
name yes yes yes
rank 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 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,
    "startTime": "2020-05-23T12:26:35.000000Z",
    "endTime": "2020-06-23T12:26:35.000000Z"
}

Order deletion

Order deletion follows similar rules to editing. Orders can be deleted or cancelled only when the order is in one of the following states: PENDING, IN PROGRESS, RECEIVED and REQUESTED. An order deletion is acheived by creating a DELETE request to the orders endpoint with the ID of the 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