/

API Satellite Tasking Ordering

Place and track tasking orders through the API.


Introduction

This guide shows you how to place tasking orders using the UP42 API and assumes that you already chose the data product and its corresponding ID from the article Satellite Tasking.

1. Authenticate

The first step is to obtain the project token. For more information, please refer to Authenticate.

2. Select the data product

UP42 provides access to 3 collections that consist of more data products. A data product is an image with a certain radiometric and geometric processing level. To locate the data product and its corresponding ID, you can use one of the 2 methods below.

Method 1: Select from the collection table

Choose one of the 3 collections and find the data product IDs:

  1. Pléiades Neo
  2. Pléiades
  3. SPOT 6/7

Method 2: Select from the data product endpoint

Alternatively, you can list all the data products using this API call:

curl -L -s -H "Authorization: Bearer $PTOKEN" -H 'Accept: application/json' \
https://api.up42.com/data-products/

If we select the Pléiades Neo collection, we can extract all the IDs from its corresponding data products using the API call below. For more information, please refer to Pléiades Neo.

curl -L -s -H "Authorization: Bearer $PTOKEN" -H 'Accept: application/json' \
https://api.up42.com/data-products/ | jq '.data[] |  select(.collectionName ==\
 "pneo-tasking") .id'

3. Build the request body

Create a request body with the tasking order parameters from the table below.

ParameterDescriptionExample
dataProductThe ID of the data product to be ordered.ce7360e8-d667-46cd-92cd-b456f5fb0702
params.displayNameHuman-readable name of the order.My satellite tasking order
params.acquisitionStartThe beginning of the image capture interval (ISO 8601).2021-12-15T09:45:51.552880Z
params.acquisitionEndThe end of the image capture interval (ISO 8601).2021-12-31T09:45:51.552880Z
params.geometryA GeoJSON geometry object defined in WGS84 (EPSG 4326).{"coordinates":
[[[13.4291473031044,52.494402422398366], [13.428629636764526,52.49390434442823], [13.430040478706358,52.493437289140736], [13.430458903312683,52.493920674942935], [13.4291473031044,52.494402422398366]]],
"type": "Polygon"}
params.extraDescriptionAdditional details about the tasking operation.Capture high resolution images over my AOI
params.cloudCoverageThe maximum percentage of cloud cover for the images (0-100).20
params.incidenceAngleThe angle between the ground normal and look direction from the satellite, expressed in degrees (0-90).12

Request body sample (saved in a separate file tasking_order_request.json):

{ "dataProduct": "ce7360e8-d667-46cd-92cd-b456f5fb0702",
  "params": {
    "displayName": "My satellite tasking order",
    "acquisitionStart": "2021-12-15T09:45:51.552880Z",
    "acquisitionEnd": "2021-12-31T09:45:51.552880Z",
    "geometry": {
      "coordinates": [[[13.4291473031044,52.494402422398366],
                       [13.428629636764526,52.49390434442823],
                       [13.430040478706358,52.493437289140736],
                       [13.430458903312683,52.493920674942935],
                       [13.4291473031044,52.494402422398366]]],
      "type": "Polygon"},
    "extraDescription": "Capture high resolution images over my AOI",
    "cloudCoverage": 20,
    "incidenceAngle": 12
  }}

This step assumes that users are placing an order for the first time and have not yet obtained access to tasking collections. If you already have access, skip this and go directly to 6. Place a tasking order.

Make sure to create a variable for your workspace ID:

workspace_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Place a tasking order using the request body you previously created (tasking_order_request.json):

curl -L -s -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer \
$PTOKEN" -d @tasking_order_request.json https://api.up42.com/workspaces/$workspace_id/orders

If the API call was successful, you receive a 451 error message:

{"data":null,"error":{"code":451,"message":"Access is not granted for collection \
pneo-tasking. To request access please go to Up42 Console/Access Requests \
https://console.up42.com/settings/access?collection=pneo-tasking","details":null}}

5. Request access to the restricted collection

Open the access request form by clicking on the collection link (https://console.up42.com/settings/access?collection=pneo-tasking).

You will be redirected to a new window, where you need to fill in the necessary details.

RequestAccess
Access Request Form

Submit the request form. Please note that our team will get back to you in maximum 2 working days.

You will receive an email with the subject Access to pneo-tasking approved. This means that access has been granted and you can now continue placing the tasking order. To verify that the access request has been approved, you can also go to the dashboard Access Requests.

AccessEmailReceived
Access Granted

6. Place a tasking order

Repeat the tasking order placement by using the previous API call:

curl -L -s -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer \
$PTOKEN" -d @tasking_order_request.json https://api.up42.com/workspaces/$workspace_id/orders

This API call returns a JSON response that contains the order ID. The tasking order has been successfully placed.

{ "data": {"id": "182aa8ae-180e-49a7-9af7-8ef497909e4d"},  
  "error": null }

7. Track the tasking order

Use the order ID to track the order you just placed and make sure to create a variable for your order ID:

order_id=182aa8ae-180e-49a7-9af7-8ef497909e4d

curl -L -s -H 'Content-Type: application/json' -H "Authorization: Bearer \
$PTOKEN" https://api.up42.com/workspaces/$workspace_id/orders/$order_id

Track the status of this order:

curl -L -s -H 'Content-Type: application/json' -H "Authorization: Bearer \
$PTOKEN" https://api.up42.com/workspaces/$workspace_id/orders/$order_id | jq '.data.status'

8. Tasking operation feasibility evaluation

After the order is officially placed, the operations team will assess the feasibility of this tasking operation. This means that the operations team evaluates the order parameters (cloud cover, local climate and seasonal restrictions, acquisition interval, incidence angle etc.) and classifies the tasking operation as easy or difficult to complete.

9. Payment

Depending on how achievable this tasking operation is, the operations team will provide the total price for the tasking operation.

10. Activation of the tasking operation

The tasking operation is activated and the image acquisition officially starts.

11. Download tasked images

When new images have been captured during the tasking operation, they are delivered as assets to the Storage. To download the assets, first create a variable for the asset ID using the following API call:

asset_id=$(curl -L -s -H 'Content-Type: application/json' -H "Authorization: Bearer \
$PTOKEN" https://api.up42.com/workspaces/$workspace_id/orders/$order_id | jq -r '.data.assets[]')

Download the asset with this API call:

curl -L -s -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer \
$PTOKEN" https://api.up42.com/workspaces/$workspace_id/assets/$asset_id/downloadUrl | jq '.data.url'

The URL from the response will redirect you to the tasked image, which is downloaded as a ZIP file. You can simply click on this URL or use the following API call that downloads the image as a ZIP file (my_first_tasked_image.zip):

curl -L -s -H "Authorization: Bearer $PTOKEN" -o my_first_tasked_image.zip \
"https://storage.googleapis.com/user-storage-interstellar-prod/workspace/\
456793ec1b-cd2c-4516-aa80-8f065fc91234/order/TASKING/oneatlas/\
4c51b20f-eff4-4e56-b3df-3ef68fb42af5/ed0f3b47-d756-4777-90e2-2c6004c562f2.zip?\
response-content-disposition=attachment%3B%20filename%3Ded0f3b47-d756-4777-90e2\
-2c6004c562f2.zip&[email protected]\
gserviceaccount.com&Expires=1636379372&Signature=ClHjDxJP7WHkU4sijyozdE8FfCnqmk0ksR7"

Congratulations! You downloaded your first image captured through a tasking operation.