/

Data ordering (API)

Get a quote and place a tasking order.


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:

  1. Getting the product schema: after we decided on the product we want to get from our tasking order we obtain the product schema.
  2. 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.

ParameterDescriptionExample
dataProductThe ID of the data product to be ordered.bd102407-1814-4f92-8b5a-7697b7a73f5a
params.displayNameHuman-readable name of the order.My satellite tasking order
params.acquisitionStartThe beginning of the image capture interval (ISO 8601).2022-08-01T00:00:00.000Z
params.acquisitionEndThe end of the image capture interval (ISO 8601).2022-10-01T00:00:00.000Z
params.acquisitionModeOne of mono, stereo or tristereo.mono
params.radiometricProcessingOne of reflectance, display or basic.reflectance
params.geometricProcessingOne of primary, projected or ortho.ortho
params.spectralProcessingThe combination of bands to be delivered.bundle
params.deliveredAsThe file format of the images to be delivered.geotiff
params.geometryA 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.extraDescriptionAdditional details about the tasking operation.Capture high resolution images over my AOI
params.cloudCoverageThe maximum percentage of cloud cover for the images (0-100).10
params.incidenceAngleThe angle between the ground normal and look direction from the satellite, expressed in degrees (0-90).10
params.pixelCodingThe pixel coding is relates to the amount of color information in an image.12bits
params.projectionProjection 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:

Loading...

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).