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:
- Getting the product schema: after we decided on the product we want to get from the tasking order we obtain the product schema.
- 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.
Parameter | Description | Example |
---|---|---|
dataProduct | The ID of the data product to be ordered. | bd102407-1814-4f92-8b5a-7697b7a73f5a |
params.displayName | Human-readable name of the order. | My satellite tasking order |
params.acquisitionStart | The beginning of the image capture interval (ISO 8601). | 2022-08-01T00:00:00.000Z |
params.acquisitionEnd | The end of the image capture interval (ISO 8601). | 2022-10-01T00:00:00.000Z |
params.acquisitionMode | One of mono, stereo or tri-stereo. | mono |
params.radiometricProcessing | One of reflectance, display or basic. | reflectance |
params.geometricProcessing | One of primary, projected or ortho. | ortho |
params.spectralProcessing | The combination of bands to be delivered. | bundle |
params.deliveredAs | The file format of the images to be delivered. | geotiff |
params.geometry | A GeoJSON geometry object defined in EPSG:4326 (WGS84). | {"coordinates": [[[-79.64181869909564, 9.072695881506306],[-79.43872941845207, 9.072695881506306],[-79.43878601941417, 8.870349117277087],[-79.64176209813355, 8.870349117277087],[-79.64181869909564, 9.072695881506306]]] "type": "Polygon"} |
params.extraDescription | Additional details about the tasking operation. | Capture high resolution images over my AOI |
params.cloudCoverage | The maximum percentage of cloud cover for the images (0-100). | 10 |
params.incidenceAngle | The angle between the ground normal and look direction from the satellite, expressed in degrees (0-90). | 10 |
params.pixelCoding | The pixel coding is relates to the amount of color information in an image. | 12bits |
params.projection | Projection EPSG in which you want the image (confirm this for each satellite before ordering) | 4326 |
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
To find your workspace ID, please follow the instructions from the article Workspaces.
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.