Place an order

The following steps will show you how to place a tasking order using the API.

Request tasking access

If you want to use a tasking collection for the first time, you need to request access to it. For more information on access requests, see Restrictions.

An email from the Customer Success team usually takes up to 3 days. You can review your access request status on the Access Requests page.

API Tools

In order to discover the available data products and place orders, users can use tools for making the API calls. We also have some recommended tools to make API calls.

Authentication

To make API requests, you need to authenticate with an access token. This token is generated from the project credentials (project ID and API key). For more information on how to authentication process to make API requests, check the Authentication article.

Tasking work steps

The order placement is done via a POST HTTP request that receives as payload a JSON document. This document has some fields that are the same for any product, while others are dependent on the specific product.

To find out exactly which parameters to use we need first to obtain the product schema.

Placing order then consists of two steps:

1. Getting the product schema: after we decided on the product we want to get from the tasking order we obtain the product schema.
2. Placing the order based on the product schema.

Get a product schema

For the sake of illustration we are going to be tasking the Pléiades satellite constellation to obtain an analytic product. So that we can post-process it to derive all manner of insights, e.g., vegetation/crop analysis, etc.

curl -L 'https://api.up42.com/data-products/bd102407-1814-4f92-8b5a-7697b7a73f5a'

The output is displayed on the gist: https://gist.github.com/up42-epicycles/5104327a79a34a19c611dfe370050d96

The important thing here is the product id: bd102407-1814-4f92-8b5a-7697b7a73f5a. With it we retrieve the product schema:

Get a JSON schema

curl -L -s -H "Authorization: Bearer $PTOKEN" \
    https://api.up42.com/orders/schema/bd102407-1814-4f92-8b5a-7697b7a73f5a

This returns the following JSON document. This defines the JSON schema for the parameters of a Pléaides analytic tasking product. There are sub-schemas on the document that enumerate the possible values of things like acquisitionMode, radiometricProcessing, geometricProcessing, spectralProcessing, etc. In this case we chose, respectively, mono, reflectance, ortho and bundle.

Create a request body

Create a request body with the tasking order parameters from the table below.

The example below is a request body for placing a tasking order for Pléiades:

Place a tasking order

Place the tasking order by using the request body you previously created:

curl -L -s -X POST -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $PTOKEN" -d @pleiades_analytic_mono_tasking_request.json \
    https://api.up42.com/workspaces/$workspace_id/orders

This API call returns a JSON response that contains the order ID. The tasking order has been successfully placed.

{ "data": {"id": "182aa8ae-180e-49a7-9af7-8ef497909e4d"},
  "error": null }

Feasibility evaluation

After the order is officially placed, the Customer Success team will assess the feasibility of this tasking operation. This means that the Customer Success team evaluates the tasking parameters (cloud cover, local climate and seasonal restrictions, acquisition interval, incidence angle etc.). After the feasibility analysis, the Customer Success team classifies the tasking operation as easy or difficult to complete.

Payment

Depending on how achievable the tasking operation is, the Customer Success team will provide a quotation with the final price.

Activation of the tasking order

Once the tasking order is placed, the tasking operation is activated and the image acquisition officially starts.

You manage an order using the API.