Assured Tasking tutorial

Read this tutorial if you are looking for a step-by-step guide on how to create a satellite tasking order, monitor its status and get data delivered from start to finish using Restful API.

In this guide, you will learn how to:

Select a satellite pass for the assured tasking order
Retrieve the price of the order
Place the tasking order
Monitor the order’s status
Receive the data

The process for feasibility check and order placement differ for standard tasking and assured tasking products. This tutorial describes the process for placing a Assured Tasking Order.

Exploring available passes

As mentioned in the Tasking feasibility page, the feasibility request for the assured tasking product returns information about the available passes over the target.

The following example shows how you can create a feasibility request for the assured product:

export CONTRACT_ID="xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
export ACCESS_TOKEN="xxx…xxx"
curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/feasibilities/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "type": "Feature",
  "geometry": {
    "coordinates": [
      -26.213044,
      67.63173
    ],
    "type": "Point"
  },
  "properties": {
    "datetime": "2024-04-01T00:00:00/2024-04-08T23:59:59",
    "product": "assured"
  }
}'

note

Please note that the feasibility request may take some time to process. It can take up to one minute to provide a result. To check the status of the request, you can use the /otm/v2/${CONTRACT_ID}/tasking/feasibilities/${FEASIBILITY_ID} endpoint.

Once the feasibility request is processed, you can retrieve the available passes for the selected location and a timeframe:

export FEASIBILITY_ID="xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
curl -X GET "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/feasibilities/${FEASIBILITY_ID}/response" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Here is an example of the response:

{
    "type": "FeatureCollection",
    "features": [
        {
            "bbox": [
                -26.213044,
                67.63173,
                -26.213044,
                67.63173
            ],
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -26.213044,
                    67.63173
                ]
            },
            "properties": {
                "datetime": "2024-04-02T16:02:24+00:00/2024-04-02T16:44:57+00:00",
                "product": "assured",
                "created_at": "2024-03-26T15:22:47.801650",
                "updated_at": "2024-03-26T15:22:47.801650",
                "satvu:day_night_mode": "day-night",
                "max_cloud_cover": 100,
                "min_off_nadir": 2.2502104916152676,
                "max_off_nadir": 44.0818123268789,
                "min_gsd": 3.753866137463882,
                "max_gsd": 6.706020499472806,
                "min_sun_el": 22.28186477676762,
                "max_sun_el": 22.444073991687915
            },
            "id": "9800b80b-cea1-4a91-b151-9dc444b89270",
            "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRldGltZSI6IjIwMjQtMDQtMDJUMTY6MDI6MjQrMDA6MDAvMjAyNC0wNC0wMlQxNjo0NDo1NyswMDowMCIsImxvY2F0aW9uIjpbLTI2LjIxMzA0NCw2Ny42MzE3M10sImV4cCI6MTcxMTQ3ODU1MywiaXNzIjoiaHR0cHM6Ly9hcGkucWEuc2F0ZWxsaXRldnUuY29tL290bS8ifQ.8r5HlWJc9uGcHP4olzOAJDLR_yJZ7dBuJ3XJNlCuVpq0kNGS8SPVRJC2O9jua1KheCFBE5Ezir3pgeI0ImPGBA"
        },
        {
            ...
        }
    ],
    "id": "d1643376-567d-4af0-93dc-a7b76eb349ca",
    "links": [
        {
            "href": "https://...",
            "rel": "self",
            "method": "GET",
            "body": null,
            "merge": false,
            "type": "application/json",
            "title": null
        },
        {
            "href": "https://...",
            "rel": "request",
            "method": "GET",
            "body": null,
            "merge": false,
            "type": "application/json",
            "title": null
        }
    ],
    "status": "feasible",
    "contract_id": "..."
}

Now using the signature value from the feasibility response, you can place an assured tasking order.

note

Please note, that the off-nadir angle, sun elevation angle and ground sample distance values are estimated and might differ from the final image parameters. While placing an order, those will be set to the maximum to ensure data collection.

Price estimation

We want to ensure transparent pricing of the tasking order, so we provide an endpoint you can use to retrieve the price of your tasking order.

At this stage you must also specify the licence_level and optionally select a Catalog withhold addon (addon:withhold) which are available in your contract. For more details on viewing the options available on your contract, see Contract Information

curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/feasibilities/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "type": "Feature",
  "geometry": {
    "coordinates": [
      -26.213044,
      67.63173
    ],
    "type": "Point"
  },
  "properties": {
    "datetime": "2024-04-01T00:00:00/2024-04-08T23:59:59",
    "product": "assured",
    "licence_level" : "Evaluation Licence",
    "addon:withhold": "P7D"
  }
}'

In the response body, you will see your original request and the price field with the price of the order. This price will be deducted from your credit limit once you place an order.

Placing a tasking order

To place an assured tasking order, the signature value from the feasibility check step is required, the product name and a selected withhold option.

export SIGNATURE="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/orders/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "properties": {
    "product": "assured",
    "addon:withhold": "P7D",
    "licence_level" : "Evaluation Licence",
    "signature": "${SIGNATURE}"
  }
}'

This will return a JSON with the order information and the order ID (id), which you can use to retrieve information about the order.

You will notice a status field in the properties object. Shortly after the initial created status the value should transition to staged. More information about statuses and tasking order is available under Tasking order.

Data download

Once the order status changes to fulfilled, you can download the data.

We provide a data download endpoint that requires you to specify the order ID. When you run it, the endpoint response is the link to the file. Follow the link and save data as a .zip archive.

curl -X GET "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/orders/${ORDER_ID}/download" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Exploring available passes​

Price estimation​

Placing a tasking order​

Data download​

Exploring available passes

Price estimation

Placing a tasking order

Data download