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 all available data products, call the Get data products endpoint with the name of the chosen collection in query parameters. Retrieve the data product ID of the product you want to proceed with.
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 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.
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. The structure of request bodies for estimation and order placement requests is the same.
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": [ ... ]
}
To create an order, call the Create an order endpoint with your workspace ID as the query parameter.
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
}
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.