Assured Tasking Order creation

The Planet Tasking API is a REST based API, which can be integrated into any service, regardless of the language used. Assured Tasking Orders are one of the varieties of Tasking Orders that can be created via the Tasking API.

The creation of an Assured Tasking Order follows the same rules as normal orders, but with a couple of extra steps along the way.

Request imaging windows

Assured Tasking allows the creation of a Tasking Order that is "assured" to take place at a given time and date of a satellite passing over the provided geo-coordinate. To do this, we first query the Tasking API to retrieve the available imaging windows that will satisfy the provided geo-coordinates and timeframe. This is done by calling the tasking/v2/imaging-windows/ endpoint of the Tasking API:

  curl --request POST \
    --url https://api.planet.com/tasking/v2/imaging-windows/ \
    --header 'authorization: api-key <YOUR_API_KEY>' \
    --header 'content-type: application/json' \
    --data '{
        "start_time": "2020-07-24T00:52Z",
        "end_time": "2020-07-26T00:52Z",
        "geometry": {
            "coordinates": [
                61.874999999998835,
                48.69096039092497
            ],
            "type": "Point"
        },
        "pl_number": "<PL-YourPlanetNumber>",
        "product": "Assured Tasking",
        "satellite_elevation_angle_min": 60,
        "satellite_elevation_angle_max": 90
    }'

The required fields for requesting the available imaging windows are:

• geometry: a GeoJSON object
• pl_number: your Planet Number, which begins with PL
• product: here, the product is Assured Tasking

The request also includes the optional satellite_elevation_angle_min and satellite_elevation_angle_max fields, in this case set to 60° and 90°, respectively. These angles define the desired orientation of the satellite when it takes the image. Note that the more restrictive the angle, the lower the likelihood that the Tasking Order succeeds.

The response body is empty, instead we have to look into the response headers for the location field, which contains a url path with a search_id that we then use in a GET request to the same endpoint:

  curl --request GET \
    --url 'https://api.planet.com/tasking/v2/imaging-windows/?search_id=<SEARCH_ID>' \
    --header 'authorization: api-key <YOUR_API_KEY>' \
    --header 'content-type: application/json'

This request returns an array of available imaging windows:

    {
      "count": 2,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": "b964e2a8-0a8b-4a83-a05d-8ac025c0f799",
          "assured_tasking_tier": "STANDARD",
          "geometry": {
            "geojson": {
              "type": "Point",
              "coordinates": [
                61.874999999998835,
                48.69096039092497
              ]
            },
            "geometry": {
              "type": "Point",
              "coordinates": [
                61.875,
                48.69096
              ]
            }
          },
          "start_time": "2020-07-24T06:48:56.333000Z",
          "end_time": "2020-07-24T06:50:03.528000Z",
          "start_off_nadir": 31.22424,
          "end_off_nadir": 31.23145,
          "created_time": "2020-07-23T15:41:06.820966Z"
        },
        {
          "id": "6891485e-3c9a-475b-8504-081d086b5fcd",
          "assured_tasking_tier": "STANDARD",
          "geometry": {
            "geojson": {
              "type": "Point",
              "coordinates": [
                61.874999999998835,
                48.69096039092497
              ]
            },
            "geometry": {
              "type": "Point",
              "coordinates": [
                61.875,
                48.69096
              ]
            }
          },
          "start_time": "2020-07-24T06:27:33.841000Z",
          "end_time": "2020-07-24T06:28:41.827000Z",
          "start_off_nadir": 31.22825,
          "end_off_nadir": 31.22892,
          "created_time": "2020-05-23T15:41:06.828251Z"
        }
      ]
    }

Creating an Assured Tasking Order

Each of these windows represents a time period that a satellite will be passing over the provided geo-coordinates. Taking one of these windows, we can then create an Assured Tasking Order that includes the id of the selected window.

  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': 'Assured Tasking Order 01',
        'geometry': {
            'type': 'Point',
            'coordinates': [
                61.874999999998835,
                48.69096039092497
            ]
        },
        'imaging_window': '6891485e-3c9a-475b-8504-081d086b5fcd'
    }