Order Lock-In creation

The Planet Tasking API is a REST based API, which can be integrated into any service, regardless of the language used. Order Lock-In is one of the varieties of Tasking Order that can be created via the Tasking API, and below is an example of how this can be achieved.

The creation an Order Lock-in Tasking Order follows the same rules as normal orders but with some extra steps along the way.

Request imaging windows

Order Lock-In allows the creation of a Tasking Order that is "locked-in" to a time & date of a satellite passing over the provided geo-coordinate. To do this, we first have to query the Tasking API to retrieve the available satellites that will be passing over the geo-coordinates in a given timeframe. This is done by calling the /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"
    }
}'

As shown in the above example, the required fields are 'start_time', 'end_time' and 'geometry', which is a GeoJSON object. The response will contain a "search_id" that then needs to be used to make a GET request to the same endpoint:

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

This request will return the array of available imaging windows i.e.:

    {
      "count": 2,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": "b964e2a8-0a8b-4a83-a05d-8ac025c0f799",
          "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",
          "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 a Locked-in Order

Each of these windows represents a timeperiod that a satellite will be passing over the provided geo-coordinates. Taking one of these windows, we can then create a Tasking Order that will include the "id" of the selected window. NOTE: that the geo-coordinates provided to the /v2/imagine-windows/ request MUST also be used in the creation of the Order, otherwise the order will not be accepted.

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': [
            61.874999999998835,
            48.69096039092497
        ]
    },
    'scheduling_type': 'LOCK_IN",
    'imaging_window': '6891485e-3c9a-475b-8504-081d086b5fcd'
}