Tasking API

Overview

Request a satellite or an aircraft to capture your designated area with certain criteria, such as processing levels and data specifications.

Step 3. Review feasibility study options

Step 1. Get access

If you are ordering a certain catalog collection for the first time, complete the access steps.

Select a collection

Review the specifications of tasking collections and select a collection for ordering.

To get a list of all collections, call the Get geospatial collections endpoint. Select the collection you want to proceed with and retrieve its name. Tasking collections have the -tasking suffix in their names.
Request access

If you order a collection for the first time and it has an ACCESS_APPROVAL_REQUIRED string in the integrations array, request access to the collection. Your request will be reviewed in up to 3 working days. You’ll get an email once a decision has been reached. You can review your access request status on the Access requests page.

After you have access, you won’t need to request access again.
Accept the EULA

If you want to order the chosen collection for the first time, review and accept its end-user license agreement (EULA). If a EULA is updated, you need to re-accept it before creating your next order.

Step 2. Create an order

Select a data product

Data products are a type of imagery with a specific geometric and radiometric processing level and file format. All collections have different data products corresponding to their technical specifications.

To get a list of data products available for the collection you have selected, call the Get a geospatial collection endpoint with the name of the chosen collection as the path parameter. Retrieve the data product ID of the product you want to proceed with.

Get a JSON schema of an order form

Orders require different parameters depending on the data product.

To see detailed information about the parameters needed to create an order for a specific data product, call the Get a JSON schema of an order form endpoint with the data product ID as the path parameter.

How to read tasking order schemas

For example, this is Capella Space tasking collection’s schema:

JSON

    {
  "$schema": "https://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {
    "geometry": {
      "title": "Geometry",
      "type": "object",
      "allOf": [
        {
          "$ref": "#/definitions/Polygon"
        }
      ]
    },
    "displayName": {
      "title": "Order name",
      "type": "string"
    },
    "extraDescription": {
      "title": "Description",
      "type": "string"
    },
    "acquisitionStart": {
      "title": "Start",
      "type": "string",
      "format": "date-time"
    },
    "acquisitionEnd": {
      "title": "End",
      "type": "string",
      "format": "date-time"
    },
    "acquisitionMode": {
      "title": "Acquisition mode",
      "description": "In Spotlight (Spot) mode, the antenna beam is focused on a point on the Earth for an extended period. Azimuth resolution increases with the dwell time of the antenna beam on the target, and range resolution increases with the bandwidth. With Sliding spotlight (Site) instead of illuminating a fixed point on the ground, the acquisition angle is slowly varied to slide the illumination point along the ground. Sliding spotlight provides excellent image resolution with larger area coverage than spotlight. In Stripmap (Strip) mode the center of the antenna beam moves in tandem with the satellite.",
      "type": "string",
      "allOf": [
        {
          "$ref": "#/definitions/acquisitionMode"
        }
      ]
    },
    "incidenceAngle": {
      "title": "Maximum incidence angle (°)",
      "description": "Maximum allowed incidence angle in degree.",
      "minimum": 0,
      "maximum": 90,
      "type": "integer"
    },
    "polarization": {
      "title": "Polarization",
      "description": "This constellation is a single-polarization system producing horizontal transmit, horizontal receive (HH) or vertical transmit, vertical receive (VV) imagery. Different polarizations provide different received backscatter data, which can highlight various electrical and geometric properties of the imaged area like surface roughness and moisture content.",
      "type": "string",
      "allOf": [
        {
          "$ref": "#/definitions/polarization"
        }
      ]
    }
  },
  "required": [
    "geometry",
    "displayName",
    "acquisitionStart",
    "acquisitionEnd",
    "acquisitionMode",
    "incidenceAngle",
    "polarization"
  ],
  "definitions": {
    "Polygon": {
      "title": "Polygon",
      "description": "Polygon Model.",
      "type": "object",
      "properties": {
        "type": {
          "title": "Type",
          "default": "Polygon",
          "const": "Polygon",
          "type": "string"
        },
        "coordinates": {
          "type": "array",
          "items": {
            "type": "array",
            "minItems": 4,
            "items": {
              "type": "array",
              "minItems": 2,
              "maxItems": 2,
              "items": {
                "type": "number"
              }
            }
          }
        }
      },
      "required": ["coordinates"]
    },
    "acquisitionMode": {
      "title": "acquisitionMode",
      "anyOf": [
        {
          "const": "spotlight",
          "title": "Spotlight"
        },
        {
          "const": "stripmap",
          "title": "Stripmap"
        },
        {
          "const": "sliding_spotlight",
          "title": "Sliding Spotlight"
        }
      ]
    },
    "polarization": {
      "title": "polarization",
      "anyOf": [
        {
          "const": "hh",
          "title": "HH"
        },
        {
          "const": "vv",
          "title": "VV"
        }
      ]
    }
  },
  "additionalProperties": false
}

The parameters in the properties field are the properties you can specify. In this example, the following properties can be specified:

Geometry (in the polygon/AOI format)
Order name
Order description
Acquisition start and end dates
Acquisition mode (select one of the following):
- Spotlight
- Stripmap
- Sliding Spotlight
Incidence angle, from 0° to 90°
Polarization (select one of the following):
- HH
- VV

In the required field, check which properties must be specified in an order placement request. The order placement will fail without them.

Estimate the cost

Before creating an order, you can estimate the price in UP42 credits. The factors considered in the final price calculation are the size of the area of interest, the data collection, and the chosen characteristics of the data product.

To see a cost estimation before creating an order, call the Estimate the cost of an order endpoint.

Create a request body for the endpoint as follows:
- In displayName, assign a custom name to your order.
- In dataProduct, use the chosen data product ID.
- In featureCollection, use the geometry you want to order.
- In params, use the required request body schema format for the chosen data product.
JSON
```
    {
  "displayName": "SPOT tasking order",
  "dataProduct": "b1f8c48e-d16b-44c4-a1bb-5e8a24892e69",
  "featureCollection": { ... }, // The geometry in GeoJSON format
  "params": { ... } // The format of the payload is different for different data products
}

  
```
The response returns the overall credit amount that will be deducted from your credit balance if you decide to proceed with the ordering:
JSON
```
    {
  "summary": {
    "totalCredits": 14424, // The estimate of the order cost, in credits
    "totalSize": 8.48,
    "unit": "SQ_KM"
  },
  "results": [ // Check this if you have several geometries in your order
    {
      "index": 0,
      "credits": 13000,
      "size": 8,
      "unit": "SQ_KM"
    },
    {
      "index": 1,
      "credits": 1424,
      "size": 0.48,
      "unit": "SQ_KM"
    }
  ],
  "errors": [ ... ]
}

  
```
Create an order

To create an order, call the Create an order endpoint with your workspace ID as the query parameter. Use the same request body structure used for estimating cost.

If you need to change the tags of the order after it has been created, call the Update an order endpoint with the order ID as the path parameter and the new tags in the request body.

Step 3. Review feasibility study options

Depending on the collection and parameter combination, your order might or might not require a feasibility study. To check whether a feasibility study will be required for your tasking order, call the Check feasibility study requirements endpoint.

If a feasibility study isn’t required

The order is considered feasible within the specified parameters and will move to the activation request stage.
If a feasibility study is required

After an order is placed, the Operations team will conduct a feasibility study. They will evaluate the tasking parameters with the provider, and then will present the following assessments:
- The order is possible with the given parameters.
- The order requires modifications with suitable options proposed.
You’ll receive an email notifying you when your order feasibility has been assessed.

To get a list of feasibility studies for all tasking orders, call the Get feasibility studies for tasking orders endpoint. Check the content.options.description field for clarification on how the provided feasibility options are different from each other. Retrieve the ID of the option you want to proceed with.

To accept one of the proposed feasibility study options, call the Choose a feasibility study option endpoint with the feasibility study ID as the path parameter and the option ID in the request body. You can only perform actions with feasibility studies with the NOT_DECIDED status.

You can later check the accepted option in the content.decisionOption object of the Get feasibility studies for tasking orders endpoint’s response.

Step 4. Activate your order

Review a quotation

After accepting a feasibility study option, you’ll receive a price quotation for your order. To get quotations for all tasking orders, call the Get quotations for tasking orders endpoint. Check the content.creditsPrice field for the amount of credits that will be charged. Retrieve the ID of the quotation, if you want to proceed with it.
Accept the quotation

Once you accept the tasking quotation, the credits for that order will be deducted. The transaction can’t be reversed.

To activate your order, you need to accept the quotation issued for it. Call the Decide on a quotation endpoint with the quotation ID as the path parameter. This operation is only allowed on quotations with the NOT_DECIDED status.

Step 5. Monitor orders

Check orders

Get information about tasking orders as follows:

Retrieve information about all orders by calling the Get orders endpoint.
Retrieve information about a specific order by calling the Get an order endpoint with the order ID as the path parameter.

The most useful parameter for monitoring is order status. Tasking orders have the following types of status parameters:

status: the primary indicator of the order’s status.
subStatus: the secondary status indicator, clarifying whether there is an action needed from you.

JSON

    {
  "displayName": "Pléiades Neo over North America",
  // Other parameters
  "orderDetails": {
    "subStatus": "FEASIBILITY_WAITING_UPLOAD"
    // Other parameters
  },
  "status": "CREATED"
}

Depending on the specified order parameters, the tasking acquisition time frames will vary.

Order statuses

API status	Description	Console status
`CREATED`	The order has been created, but not yet placed.	Placed
`PLACEMENT_FAILED`	An error occurred while placing the order. Please wait until it’s resolved.	Placed
`BEING_PLACED`	The order is being placed.	Placed
`PLACED`	The order has been placed.	Placed
`BEING_FULFILLED`	The order is in progress. Some assets may already be delivered to your storage.	In progress
`FULFILLED`	The order is complete, and all assets have been delivered to your storage.	Completed
`FAILED_PERMANENTLY`	The order has permanently failed or has been canceled.	Canceled

Order substatuses

API subtatus	Description	Console status
`FEASIBILITY_WAITING_UPLOAD`	Wait for the feasibility study.	Wait for feasibility
`FEASIBILITY_WAITING_RESPONSE`	Choose a feasibility study option.	Feasibility is ready
`QUOTATION_WAITING_UPLOAD`	Wait for the quotation.	Wait for quotation
`QUOTATION_WAITING_RESPONSE`	Decide on the quotation.	Quotation is ready
`QUOTATION_ACCEPTED`	The order has been activated.	Processed
`QUOTATION_REJECTED`	The quotation has been rejected.	Wait for quotation

The following order statuses mean you can download assets from storage:

BEING_FULFILLED: some order assets might have been delivered.
FULFILLED: all order assets have been delivered.

Get coverage information

To get information about the percentage of order completion, call the Get coverage of order assets endpoint with the order ID as the path parameter. It returns the following information:

The total covered geometry, its area, and its percentage relative to the ordered geometry
The total remainder geometry, its area, and its percentage relative to the ordered geometry

JSON

    {
  "covered": {
    "sqKmArea": 99.2,
    "percentage": 64,
    "geometry": { ... } // An accumulated AOI of the covered area overlapping with the requested geometry
},
"remainder": {
    "sqKmArea": 55.8,
    "percentage": 36,
    "geometry": { ... } // An accumulated AOI of the requested geometry not yet covered by assets
  }
}