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:

Retrieve information about available catalog withholds options
Run feasibility check for the standard priority tasking order
Select a satellite pass for the assured priority 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 priority and assured priority tasking products. This tutorial describes the process for both of them.

Catalog withholds

Catalog withholds is the capability of withholding ordered tasking data from being published in the catalog. Available catalog withhold options are defined per contract. More information about it is in Accessing SatVu platform and Tasking order pages.

You can find information about available withhold options by requesting the Policy API “Active Contracts” endpoint /policy/v1/contracts.

Here is an example of the response:

{
  "result": [
    {
      "active": true,
      "addons": [
        {
          "name": "Withhold",
          "options": [
            {
              "default": true,
              "label": "No withhold",
              "uplift": 0,
              "value": "0d"
            },
            {
              "default": false,
              "label": "7 days",
              "uplift": 30,
              "value": "7d"
            }
          ]
        }
      ],
      "allowed_geographical_area": {...},
      "contract_id": "375158d5-a768-44e3-9506-0f6af8833d16",
      "end_date": {...},
      "geographical_summary": "...",
      "name": "...",
      "products": [...],
      "start_date": {...}
    }
  ]
}

The response includes the addons object with the name Withholds and the list of withhold options. Each options includes:

default - the boolean value that identifies which option is considered as the default one.
label - the human-readable name.
uplift - the price uplift coefficient in percentage based on a base price of the product.
value - the withhold value in the ISO 8601 duration format. This value is used when retrieving the price or placing a tasking order.

Standard priority tasking product

Running a feasibility check

We described the concept behind the feasibility study on the Tasking feasibility page. Using API, you will need first to create a feasibility request and then retrieve the information about it.

The following example shows how you can create a feasibility request:

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": [
      -2.7783632,
      53.3240764
    ],
    "type": "Point"
  },
  "properties": {
    "datetime": "2024-04-01T00:00:00/2024-04-31T23:59:59",
    "satvu:day_night_mode": "day",
    "max_cloud_cover": 30,
    "min_off_nadir": 0,
    "max_off_nadir": 45,
    "product": "standard"
  }
}'

Here is an example of the response:

{
  "bbox": [-2.7783632, 53.3240764, -2.7783632, 53.3240764],
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-2.7783632, 53.3240764]
  },
  "properties": {
    "datetime": "2024-04-01T00:00:00+00:00/2024-04-31T23:59:59+00:00",
    "satvu:day_night_mode": "day",
    "max_cloud_cover": 30,
    "min_off_nadir": 0,
    "max_off_nadir": 45,
    "min_gsd": 3.5,
    "max_gsd": 6.8,
    "status": "pending",
    "created_at": "2024-03-22T15:58:20.823201",
    "updated_at": "2024-03-22T15:58:20.823201"
  },
  "id": "ba6c0b66-615a-4e1a-b322-a11a6a4eba31",
  "contract_id": "...",
  "links": [
    {
      "href": "https://...",
      "rel": "self",
      "method": "GET",
      "body": null,
      "merge": null,
      "type": "application/json",
      "title": null
    },
    {
      "href": "https://...",
      "rel": "response",
      "method": "GET",
      "body": null,
      "merge": null,
      "type": "application/json",
      "title": null
    }
  ]
}

Now, using the id of a feasibility request, you can check its status with the following query:

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

The status field identifies the information about the tasking order feasibility. We recommend placing the tasking order only when the status is feasible.

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 can specify the catalog withhold option that is available in your contract.

curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/price/" 
-H "Authorization: Bearer ${ACCESS_TOKEN}" 
-H "Content-Type: application/json" 
-d '{
  "type": "Feature",
  "geometry": {
    "coordinates": [
      -2.7783632,
      53.3240764
    ],
    "type": "Point"
  },
  "properties": {
    "datetime": "2023-11-01T00:00:00/2023-12-31T23:59:59",
    "satvu:day_night_mode": "day",
    "max_cloud_cover": 30,
    "min_off_nadir": 0,
    "max_off_nadir": 45,
    "product": "standard",
    "addon:withhold": "7d"
  }
}'

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

For placing a tasking order, you need to provide your order parameters to the Create tasking order endpoint.

curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/orders/" 
-H "Authorization: Bearer ${ACCESS_TOKEN}" 
-H "Content-Type: application/json" 
-d '{
  "type": "Feature",
  "geometry": {
    "coordinates": [
      -2.7783632,
      53.3240764
    ],
    "type": "Point"
  },
  "properties": {
    "datetime": "2023-11-01T00:00:00/2023-12-31T23:59:59",
    "satvu:day_night_mode": "day",
    "max_cloud_cover": 30,
    "min_off_nadir": 0,
    "max_off_nadir": 45,
    "product": "standard",
    "addon:withhold": "7d"
  }
}'

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.

Assured priority tasking product

Exploring available passes

As mentioned in the Tasking feasibility page, the feasibility request for the assured priority 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 priority 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"
  }
}'

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 priority tasking order.

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 can specify the catalog withhold option that is available in your contract.

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",
    "addon:withhold": "7d"
  }
}'

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 priority 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": "7d",
    "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.

Tracking orders

We provide a few endpoints to retrieve information about tasking orders. You can use the “Retrieve a tasking order” endpoint to get information about a specific tasking order:

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

You can also view all your orders with “List all tasking orders” endpoint:

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

Or search orders providing more advanced parameters. The following example searches orders that are placed in the specified geometry:

curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/search/" 
-H "Authorization: Bearer ${ACCESS_TOKEN}" 
-H "Content-Type: application/json" 
-d '{
  "collections": [
    "orders"
  ],
  "intersects": {
    "coordinates": [
      [
        [
          -8.60621344099522,
          60.63920763634644
        ],
        [
          -14.213293594801314,
          45.95851155946286
        ],
        [
          10.621928171802324,
          52.72769978027327
        ],
        [
          -8.60621344099522,
          60.63920763634644
        ]
      ]
    ],
    "type": "Polygon"
  }
}'

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

Data download

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}"