Tasking

In this guide, we’ll walk you through creating a tasking order—whether it’s a single order or a recurring one—using our API. We’ll break down the complete JSON request into steps, explaining each parameter, its allowed values, and validations. For more advanced details (like detailed recurrence settings), please refer to our Tasking Documentation.

​

Step 1: Global Order Settings

​

dry_run

Before placing a real order, you can test your request with a simulation. This helps you estimate the cost of the order with current configurations without deducting any tokens from your wallet. The response of dry_run as true is same as the order placed.

• Set this to true for testing or false for a live order.

Snippet:

{
  "dry_run": false
}

​

Step 2: Define Your Order Items

The core of your request is the order_items array. For a single tasking order, you will include one object in the array. To know more about Order Items, read this page.

Snippet:

{
  "order_items": [
    { /* Order item details go here */ }
  ]
}

​

Step 3: Configure the Order Item Details

​

a. Specify the Bandset

Every tasking order requires a bandset to determine the spectral configuration. Use the Bandset API to get the suitable bandset_id for your tasking request.

Snippet:

{
  "bandset": {
    "bandset_id": "<BANDSET_ID>"
  }
}

​

b. Define Your Area of Interest (AOI)

Specify where the satellite should capture images by providing the AOI in GeoJSON format.

• Create a valid GeoJSON with type as FeatureCollection with at least one polygon.
• Remember:
  • If the total area is less than 100 km², billing will be for a minimum of 100 km².
  • For multi-polygon AOIs, ensure the distance between the closest polygon boundaries does not exceed 200 km.

Snippet:

{
  "geometry": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {},
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [<LONGITUDE_1>, <LATITUDE_1>],
              [<LONGITUDE_2>, <LATITUDE_2>],
              [<LONGITUDE_3>, <LATITUDE_3>],
              [<LONGITUDE_4>, <LATITUDE_4>],
              [<LONGITUDE_1>, <LATITUDE_1>]
            ]
          ]
        }
      }
    ]
  }
}

​

c. Give Your Order a Name

A descriptive name helps you track and manage your order later.

Snippet:

{
  "name": "Order Tasking"
}

​

d. Set Imaging Parameters

​

i. Off Nadir Angle

• Specifies the maximum off-nadir angle (in degrees) acceptable for the imagery.
• Replace <OFF_NADIR_ANGLE> with the desired value.

​

ii. Cloud Cover

• Sets the maximum allowed cloud cover percentage.
• Replace <MAX_CLOUD_COVER> with your value.

Note: For urgent or assured orders, the system might override this to 100%. See Tasking Documentation for more details.

​

iii. Delivery Speed

• Defines the delivery timeline.
• Allowed Values:
  • "STANDARD" (36 hours, no uplift)
  • "EXPEDITED" (24 hours, 20% price uplift)

Snippet:

{
  "off_nadir": "<OFF_NADIR_ANGLE>",
  "cloud_cover": "<MAX_CLOUD_COVER>",
  "delivery_speed": "STANDARD"
}

​

e. Configure Automatic Delivery (Cloud Config)

If you want the imagery to be automatically delivered to a designated store once it becomes available, you can include cloud configuration details.

• cloud_delivery Specifies the store configuration for automatic delivery.
• Provide the store ID (config) and optionally the delivery path (path).

Snippet:

{
  "cloud_delivery": {
    "config": "<STORE_ID>",
    "path": "<DELIVERY_PATH>" // e.g., "/path/to/destination"
  }
}

​

f. Associate Your Order with a Project

Each order must be linked to a project.

• Provide the project_id which you can get from List Projects API

Note: Ensure your service account is added to the project via the UI.

Snippet:

{
  "project_id": "<PROJECT_ID>"
}

​

g. Define the Recurrence Type

Specify whether this is a one-time (single tasking) or recurring (monitoring) order.

•  Use "ONCE" for a single tasking order, or another valid recurrence type (like "WEEKLY", "MONTHLY", etc.) for recurring orders.
• For More Details about recurring orders See our Tasking Documentation.

Snippet:

{
  "recurrence": "<RECURRENCE_TYPE>"
}

​

h. Set the Tasking Window

​

i. Start Date

Defines when the capture window begins.

• Use an ISO8601 formatted date (e.g., "2025-03-01T00:00:00Z").
• Must be at least 24 hours after order placement.

​

ii. End Date

Defines when the capture window ends.

• Use an ISO8601 formatted date.
• Must be later than the start_date. For recurring orders, additional rules apply (see Tasking Documentation).

Snippet:

{
  "start_date": "<START_DATE_IN_ISO8601>",
  "end_date": "<END_DATE_IN_ISO8601>"
}

​

i. Declare the Use Case

Specify the intended use for the imagery.

Snippet:

{
  "usecase": "<USE_CASE>"
}

​

Putting It All Together

Below is the complete JSON request for a tasking order, with all the pieces combined:

{
    "dry_run": false,
    "order_items": [
        {
            "bandset": {
                "bandset_id": "<BANDSET_ID>"
            },
            "geometry": {
                "type": "FeatureCollection",
                "features": [
                    {
                        "type": "Feature",
                        "properties": {},
                        "geometry": {
                            "type": "Polygon",
                            "coordinates": [
                                [
                                    [<LONGITUDE_1>, <LATITUDE_1>],
                                    [<LONGITUDE_2>, <LATITUDE_2>],
                                    [<LONGITUDE_3>, <LATITUDE_3>],
                                    [<LONGITUDE_4>, <LATITUDE_4>],
                                    [<LONGITUDE_1>, <LATITUDE_1>]
                                ]
                            ]
                        }
                    }
                ]
            },
            "name": "Order Tasking",
            "off_nadir": "<OFF_NADIR_ANGLE>",
            "cloud_cover": "<MAX_CLOUD_COVER>",
            "delivery_speed": "STANDARD",
            "project_id": "<PROJECT_ID>",
            "recurrence": "<RECURRENCE_TYPE>",
            "start_date": "<START_DATE_IN_ISO8601>",
            "end_date": "<END_DATE_IN_ISO8601>",
            "cloud_delivery": {
              "config": "<STORE_ID>",
              "path": "my-bucket/my-folder"
              },
            "usecase": "<USE_CASE>"
        }
    ]
}

​

Validation & Error Notes

• Date Validations:
  • The start_date must be at least 24 hours after order placement.
  • The end_date must be later than the start_date and conform to allowed durations.
  • For recurring orders, please see our Tasking Documentation.
• Parameter Checks:
  • Ensure all required fields (bandset, geometry, project_id, etc.) are provided and valid.
  • Values like off_nadir and cloud_cover must be within acceptable ranges.
  • delivery_speed must match one of the allowed enum values.

This guide should help you understand each part of a tasking order request and how to construct it step by step. For advanced configurations such as detailed recurrence settings, please refer to our Tasking Documentation.