Home /UP42 API

Tasking

Create and monitor tasking orders using the API.

Overview

Request a satellite or an aircraft to capture your designated area with certain criteria, such as processing levels and data specifications.

Step 1. Get access

If you are ordering a certain catalog collection for the first time, complete the access steps.

  1. Select a collection

    Review the specifications of tasking collections and select a collection for ordering.

    To get a list of all collections, call the Get geospatial collections endpoint. Select the collection you want to proceed with and retrieve its name. Tasking collections have the -tasking suffix in their names.

  2. Request access

    If you order a collection for the first time and it has an ACCESS_APPROVAL_REQUIRED string in the integrations array, request access to the collection. Your request will be reviewed in up to 3 working days. You’ll get an email once a decision has been reached. You can review your access request status on the Access requests page.

    After you have access, you won’t need to request access again.

  3. Accept the EULA

    If you want to order the chosen collection for the first time, review and accept its end-user license agreement (EULA). If a EULA is updated, you need to re-accept it before creating your next order.

Step 2. 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 data products available for the collection you have selected, call the Get a geospatial collection endpoint with the name of the chosen collection as the path parameter. 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 tasking 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.

  3. Estimate the 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 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": [ ... ]
}

  4. Create an order

    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.

Step 3. Review feasibility study options

  1. Review options

    After an order is placed, the Operations team will conduct a feasibility study. They will evaluate the tasking parameters with the provider, and then will present the following assessments:

    • The order is possible with the given parameters.
    • The order requires modifications with suitable options proposed.

    You’ll receive an email notifying you when your order feasibility has been assessed.

    To get a list of feasibility studies for all tasking orders, call the Get feasibility studies for tasking orders endpoint. Check the content.options.description field for clarification on how the provided feasibility options are different from each other. Retrieve the ID of the option you want to proceed with.

  2. Accept an option

    To accept one of the proposed feasibility study options, call the Choose a feasibility study option endpoint with the feasibility study ID as the path parameter and the option ID in the request body. You can only perform actions with feasibility studies with the NOT_DECIDED status.

    You can later check the accepted option in the content.decisionOption object of the Get feasibility studies for tasking orders endpoint’s response.

Step 4. Activate your order

  1. Review a quotation

    After accepting a feasibility study option, you’ll receive a price quotation for your order. To get quotations for all tasking orders, call the Get quotations for tasking orders endpoint. Check the content.creditsPrice field for the amount of credits that will be charged. Retrieve the ID of the quotation, if you want to proceed with it.

  2. Accept the quotation

    Once you accept the tasking quotation, the credits for that order will be deducted. The transaction can’t be reversed.

    To activate your order, you need to accept the quotation issued for it. Call the Decide on a quotation endpoint with the quotation ID as the path parameter. This operation is only allowed on quotations with the NOT_DECIDED status.

Step 5. Monitor orders

  1. Check orders

    Get information about tasking orders as follows:

    • Retrieve information about all orders by calling the Get orders endpoint.
    • Retrieve information about a specific order by calling the Get an order endpoint with the order ID as the path parameter.

    The most useful parameter for monitoring is order status. Tasking orders have the following types of status parameters:

    • status: the primary indicator of the order’s status.
    • subStatus: the secondary status indicator, clarifying whether there is an action needed from you.

    JSON 

        {
  "displayName": "Pléiades Neo over North America",
  // Other parameters
  "orderDetails": {
    "subStatus": "FEASIBILITY_WAITING_UPLOAD"
    // Other parameters
  },
  "status": "CREATED"
}

    Depending on the specified order parameters, the tasking acquisition time frames will vary.

    Order statuses
    StatusDescription
    CREATEDThe order has been created, but not yet placed.
    PLACEMENT_FAILEDAn error occurred while placing the order. Please wait until it’s resolved.
    BEING_PLACEDThe order is being placed.
    PLACEDThe order has been placed.
    BEING_FULFILLEDThe order is in progress. Some assets may already be delivered to your storage.
    DELIVERY_INITIALIZATION_FAILED
    DOWNLOAD_FAILED    		An error occurred while delivering the order assets. Please wait until it’s resolved.
    DOWNLOADEDThe order assets are being delivered to your storage.
    FULFILLEDThe order is complete, and all assets have been delivered to your storage.
    FAILED_PERMANENTLYThe order has permanently failed or has been canceled.

    Order substatuses
    StatusDescription
    FEASIBILITY_WAITING_UPLOADWait for the feasibility study.
    FEASIBILITY_WAITING_RESPONSEChoose a feasibility study option.
    QUOTATION_WAITING_UPLOADWait for the quotation.
    QUOTATION_WAITING_RESPONSEDecide on the quotation.
    QUOTATION_ACCEPTEDThe order has been activated.
    QUOTATION_REJECTEDThe quotation has been rejected.

    The following order statuses mean you can download assets from storage:

    • BEING_FULFILLED: some order assets might have been delivered.
    • FULFILLED: all order assets have been delivered.

  2. Get coverage information

    To get information about the percentage of order completion, call the Get coverage of order assets endpoint with the order ID as the path parameter. It returns the following information:

    • The total covered geometry, its area, and its percentage relative to the ordered geometry
    • The total remainder geometry, its area, and its percentage relative to the ordered geometry

    JSON 

        {
  "covered": {
    "sqKmArea": 99.2,
    "percentage": 64,
    "geometry": { ... } // An accumulated AOI of the covered area overlapping with the requested geometry
},
"remainder": {
    "sqKmArea": 55.8,
    "percentage": 36,
    "geometry": { ... } // An accumulated AOI of the requested geometry not yet covered by assets
  }
}