Skip to main content

Standard 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:

  1. Run feasibility check for the standard tasking order
  2. Retrieve the price of the order
  3. Place the tasking order
  4. Monitor the order’s status
  5. 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 Standard Tasking Order.

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.

note

Please note that the feasibility request may take some time to process. It can take up to one minute to provide a result.

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/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",
    "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​

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",
    "licence_level" : "Evaluation Licence",
    "addon:withhold": "P7D"
  }
}'
note

Please note that feasibility, price and order creation endpoints have the same payload schema for the standard tasking product.

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