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 methods.

Tasking Order creation

The creation of an order via the Tasking API is done by sending a POST request to the Tasking API tasking/v2/orders endpoint. The creation of Tasking Order can be as 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

It is possible, as part of the Tasking Order creation request, to define the desired range of angles relative to the target that the satellite should attempt to take an image. These 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. These 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_time_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:

    {
        "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
            ]
        },  
        "order_type": "IMAGE",
        "sat_elevation_angle_min": 60.0,
        "sat_elevation_angle_max": 90.0,
        "start_time": "2020-03-23T12:26:35.820963Z",
        "end_time": "2020-04-22T12:26:35.820963Z",
        "n_stereo_pov": null,
        "is_cancellable": false,
        "cancellable_until": "2021-08-05T10:18:00.000000Z",
        "requested_sqkm": 25.0,
        "created_time": "2020-03-23T12:26:36.137220Z",
        "updated_time": "2020-03-23T12:26:36.137259Z",
        "name": "test_order_426",
        "created_by": "a.user@a.fake.email.address.com",
        "status": "RECEIVED",
        "fulfilled_sqkm": 0.0,
        "capture_status_published_count": 0,
        "capture_assessment_success_count": 0,
        "capture_assessment_invalid_count": 0,
        "scheduling_type": "FLEXIBLE",
        "rrule": null,
        "exclusivity_days": 0,
        "next_planned_acquisition_time": null,
        "last_acquired_time": null,
        "imaging_window": null
    }

Strip vs Point

The previous example showed how to create a Point Tasking Order, which takes the provided geo-coordinates and generates a 5x5 km square around that point, giving an overall area of 25 km2. If you have two points geographically close to each other that need to be imaged, or require a longer (but not wider) area to be imaged, then defining a Strip Tasking Order would be more suitable. The difference is simple in that instead of providing a GEoJSON Point in the Tasking Order payload, instead a LineString is provided. For 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': 'LineString',
            'coordinates': [
                [
                   10.92041015625,
                   48.91527985344383
                ],
                [
                   10.78857421875,
                   49.0738659012854
                ]
            ]
        }
    }

Strip Tasking Orders have a fixed width of 5 km and a minimum length of 6 km and a maximum length of 100 km.

Retrieving, filtering and paginating your Tasking Orders

Once you have created your Tasking Order, you can check up on it and any other Tasking Orders you may have created by peforming a GET request on the same /orders endpoint that you used to create your Tasking Orders:

curl --request GET \
  --url https://api.planet.com/tasking/v2/orders/ \
  --header 'Authorization: api-key <YOUR_API_KEY>' \
  --header 'Content-Type: application/json'

If you want to retrieve a specific Tasking Order, you would simply append the ID of the Tasking Order to the URL, e.g. /orders/some_UUID_number

In the event that you have multiple Tasking Orders, the /orders endpoint provides filtering and pagination to help manage the response payload. Through filtering you can ensure that only those Tasking Orders that you want to see are returned. Tasking Orders can be filtered by created, start and end times, name and many other values (for a full list of available parameters see: https://developers.planet.com/docs/tasking/reference/#operation/v2_orders_list) Below is an example of request all Tasking Orders that have a name containing a given string and that were created after a particular date. Note that the created date must be a correctly formatted date/time value of the type "YYYY-mm-ddThh:mm:ssZ" and that all time are in UTC:

curl --request GET \
  --url 'https://api.planet.com/tasking/v2/orders/?name__icontains=test&created_time__gt=2021-01-01T23:59:59Z' \
  --header 'Authorization: api-key <YOU_API_KEY>' \
  --header 'Content-Type: application/json'

The parameters limit and offset are used to define the boundaries of the response pagination. limit defines how many results are returns per page and offset determines the starting index of the response. Taking this into account, the following request would return 30 results per page, starting with the 10th possible result:

curl --request GET \
  --url 'https://api.planet.com/tasking/v2/orders/?limit=30&offset=10' \
  --header 'Authorization: api-key <YOU_API_KEY>' \
  --header 'Content-Type: application/json'

The response payload will then include the key next and previous with the corresponding values containing URLs that will point to the next and previous page of results. The format of these URLs is the same as the original request in the above example.

Tasking Order Editing

The ability to edit an existing Tasking Order depends upon what needs to be changed as well as 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, REJECTED and EXPIRED cannot be edited :

| FIELD | PENDING | IN PROGRESS | |---|---|---|---| | name | yes | yes | | start_time | yes | no | | end_time | 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:

    {
        "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 and RECEIVED. 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