Data ordering (API)

Place a tasking order

Overview

After getting the access request approved we move on to placing an order.

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 our tasking order we obtain the product schema.
Placing the order based on the product schema.

Get the 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 -s -H "Authorization: Bearer $PTOKEN" -H 'Accept: application/json' \
    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:

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

returning 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 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 tristereo.	`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 WGS84 (EPSG 4326).	`{"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 }

To proceed, please go to Tasking activation (API).