Step 3. Create an order

Fill out the order form with the required parameters for the data product and create an order.


1. Select a data product

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.

2. Get a JSON schema of an order form

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 Sentinel-2 catalog collection’s schema:

JSON

    {
  "$schema": "https://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {
    "id": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "definitions": null,
  "additionalProperties": false,
  "title": "EarthSearchAwsParams"
}
  

The parameters in the properties field are the properties you can specify. In catalog collections, the only property you need to specify is the full scene ID you retrieved in Step 2. Find and preview data.

3. Estimate cost

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 type of 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": [ ... ]
}
  

4. Create an order

Credits will be deducted upon successful completion of the created catalog order. The transaction can’t be reversed.

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.
    • In params.id, use the chosen full scene ID.

JSON

    {
  "displayName": "SPOT catalog order",
  "dataProduct": "b1f8c48e-d16b-44c4-a1bb-5e8a24892e69",
  "featureCollection": { ... }, // The geometry in GeoJSON format
  "params": {
    "id": "42712243-a45c-4c8e-adfa-1ce01d27b718", // The full scene ID
    <...> // The format of the payload is different for different data products
  }
}